@teamix-evo/ui 0.1.1

package/src/components/carousel/carousel.tsx

@@ -0,0 +1,224 @@
+import * as React from 'react';
+import useEmblaCarousel, {
+  type UseEmblaCarouselType,
+} from 'embla-carousel-react';
+import { ArrowLeft, ArrowRight } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+
+type CarouselApi = UseEmblaCarouselType[1];
+type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
+type CarouselOptions = UseCarouselParameters[0];
+type CarouselPlugin = UseCarouselParameters[1];
+
+export interface CarouselProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** embla 选项透传(`loop / align / startIndex / dragFree` 等)。 */
+  opts?: CarouselOptions;
+  /** embla 插件数组(`autoplay`、`fade` 等)。 */
+  plugins?: CarouselPlugin;
+  /**
+   * 滚动方向。
+   * @default "horizontal"
+   */
+  orientation?: 'horizontal' | 'vertical';
+  /** 提供 embla API 的回调,用于业务侧自行控制(scrollNext / scrollTo 等)。 */
+  setApi?: (api: CarouselApi) => void;
+}
+
+interface CarouselContextValue {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  api: CarouselApi;
+  orientation: 'horizontal' | 'vertical';
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  canScrollPrev: boolean;
+  canScrollNext: boolean;
+}
+
+const CarouselContext = React.createContext<CarouselContextValue | null>(null);
+
+function useCarousel() {
+  const ctx = React.useContext(CarouselContext);
+  if (!ctx)
+    throw new Error('useCarousel must be used within a <Carousel />');
+  return ctx;
+}
+
+const Carousel = React.forwardRef<HTMLDivElement, CarouselProps>(
+  (
+    {
+      orientation = 'horizontal',
+      opts,
+      plugins,
+      setApi,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const [carouselRef, api] = useEmblaCarousel(
+      { ...opts, axis: orientation === 'horizontal' ? 'x' : 'y' },
+      plugins,
+    );
+    const [canScrollPrev, setCanScrollPrev] = React.useState(false);
+    const [canScrollNext, setCanScrollNext] = React.useState(false);
+
+    const onSelect = React.useCallback((a: CarouselApi) => {
+      if (!a) return;
+      setCanScrollPrev(a.canScrollPrev());
+      setCanScrollNext(a.canScrollNext());
+    }, []);
+
+    const scrollPrev = React.useCallback(() => api?.scrollPrev(), [api]);
+    const scrollNext = React.useCallback(() => api?.scrollNext(), [api]);
+
+    React.useEffect(() => {
+      if (!api || !setApi) return;
+      setApi(api);
+    }, [api, setApi]);
+
+    React.useEffect(() => {
+      if (!api) return;
+      onSelect(api);
+      api.on('reInit', onSelect);
+      api.on('select', onSelect);
+      return () => {
+        api.off('select', onSelect);
+      };
+    }, [api, onSelect]);
+
+    return (
+      <CarouselContext.Provider
+        value={{
+          carouselRef,
+          api,
+          orientation,
+          scrollPrev,
+          scrollNext,
+          canScrollPrev,
+          canScrollNext,
+        }}
+      >
+        <div
+          ref={ref}
+          className={cn('relative', className)}
+          role="region"
+          aria-roledescription="carousel"
+          {...props}
+        >
+          {children}
+        </div>
+      </CarouselContext.Provider>
+    );
+  },
+);
+Carousel.displayName = 'Carousel';
+
+const CarouselContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => {
+  const { carouselRef, orientation } = useCarousel();
+  return (
+    <div ref={carouselRef} className="overflow-hidden">
+      <div
+        ref={ref}
+        className={cn(
+          'flex',
+          orientation === 'horizontal' ? '-ml-4' : '-mt-4 flex-col',
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+});
+CarouselContent.displayName = 'CarouselContent';
+
+const CarouselItem = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => {
+  const { orientation } = useCarousel();
+  return (
+    <div
+      ref={ref}
+      role="group"
+      aria-roledescription="slide"
+      className={cn(
+        'min-w-0 shrink-0 grow-0 basis-full',
+        orientation === 'horizontal' ? 'pl-4' : 'pt-4',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+CarouselItem.displayName = 'CarouselItem';
+
+const CarouselPrevious = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof Button>
+>(({ className, variant = 'outline', size = 'icon', ...props }, ref) => {
+  const { orientation, scrollPrev, canScrollPrev } = useCarousel();
+  return (
+    <Button
+      ref={ref}
+      variant={variant}
+      size={size}
+      className={cn(
+        'absolute size-8 rounded-full',
+        orientation === 'horizontal'
+          ? '-left-12 top-1/2 -translate-y-1/2'
+          : '-top-12 left-1/2 -translate-x-1/2 rotate-90',
+        className,
+      )}
+      disabled={!canScrollPrev}
+      onClick={scrollPrev}
+      aria-label="上一张"
+      {...props}
+    >
+      <ArrowLeft />
+    </Button>
+  );
+});
+CarouselPrevious.displayName = 'CarouselPrevious';
+
+const CarouselNext = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof Button>
+>(({ className, variant = 'outline', size = 'icon', ...props }, ref) => {
+  const { orientation, scrollNext, canScrollNext } = useCarousel();
+  return (
+    <Button
+      ref={ref}
+      variant={variant}
+      size={size}
+      className={cn(
+        'absolute size-8 rounded-full',
+        orientation === 'horizontal'
+          ? '-right-12 top-1/2 -translate-y-1/2'
+          : '-bottom-12 left-1/2 -translate-x-1/2 rotate-90',
+        className,
+      )}
+      disabled={!canScrollNext}
+      onClick={scrollNext}
+      aria-label="下一张"
+      {...props}
+    >
+      <ArrowRight />
+    </Button>
+  );
+});
+CarouselNext.displayName = 'CarouselNext';
+
+export {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  type CarouselApi,
+};

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

@@ -0,0 +1,110 @@
+---
+id: cascader
+name: Cascader
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Cascader
+
+级联选择 — antd 独有补足。**等价 antd `Cascader`**。多级联动选择(地区 / 分类 / 组织架构 / 文件夹路径),选项树由 `options.children` 表达;点击触发器弹出多列面板,**叶子触发 onChange**(可改 `changeOnSelect` 为每级触发)。
+
+## When to use
+
+- 地区 / 行政区划选择(国 - 省 - 市 - 区)
+- 分类导航(电商类目、文件夹层级)
+- 组织架构选择(公司 - 部门 - 团队 - 人)
+
+## When NOT to use
+
+- 单层下拉 → `Select` / `Combobox`
+- 树形多选 → `TreeSelect`(可勾选)
+- 离散级别独立选择 → 多个 `Select` 并排(级联弱)
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `CascaderOption[]` | – | ✓ | 级联选项树(antd `options` 并集)。 |
+| `value` | `string[]` | – | – | 受控值(每层 value 数组)。 |
+| `defaultValue` | `string[]` | – | – | uncontrolled 初值。 |
+| `onChange` | `(value: string[], selectedOptions: CascaderOption[]) => void` | – | – | 值变化回调 — 触发条件:点选叶子节点或显式 changeOnSelect。 |
+| `changeOnSelect` | `boolean` | `false` | – | 每选中一级即触发 onChange(antd `changeOnSelect` 并集) — 默认仅选叶子触发。 |
+| `placeholder` | `string` | `"请选择"` | – | 占位文本。 |
+| `separator` | `string` | `" / "` | – | 路径展示的分隔符。 |
+| `disabled` | `boolean` | – | – | 整体禁用。 |
+| `className` | `string` | – | – | 触发器 className(给外层 Button)。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add cascader` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `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 -->
+
+## AI 生成纪律
+
+- **`value` 是 value 数组**(每层一个),`onChange` 第二参数给完整 `CascaderOption` 路径 — 用第二参数拿到 label / 业务字段
+- **`changeOnSelect=true`** 允许"中途选择",适合"地区可只选到省" / "分类可选到任意级"
+- **同级 `value` 必须唯一**(否则 findPath 出错)— 数据准备时务必检查
+- **大量节点(> 300)**建议懒加载:数据先只展开第一层,在 onChange 中按需 fetch 子节点并更新 options
+- **不要给 disabled 节点设可点击的子项** — 用户预期父级禁用即整支禁用
+
+## Examples
+
+```tsx
+import { Cascader, type CascaderOption } from '@/components/ui/cascader';
+import * as React from 'react';
+
+const regions: CascaderOption[] = [
+  {
+    value: 'cn',
+    label: '中国',
+    children: [
+      {
+        value: 'zj',
+        label: '浙江',
+        children: [
+          { value: 'hz', label: '杭州' },
+          { value: 'nb', label: '宁波' },
+        ],
+      },
+      {
+        value: 'jx',
+        label: '江西',
+        children: [{ value: 'nc', label: '南昌' }],
+      },
+    ],
+  },
+];
+
+// 基础
+<Cascader options={regions} placeholder="选择地区" />
+
+// 中途可选
+<Cascader options={regions} changeOnSelect />
+
+// 受控
+const [v, setV] = React.useState<string[]>(['cn', 'zj', 'hz']);
+<Cascader
+  options={regions}
+  value={v}
+  onChange={(vals, opts) => setV(vals)}
+/>
+```

package/src/components/cascader/cascader.stories.tsx

@@ -0,0 +1,108 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Cascader, type CascaderOption } from './cascader';
+
+const meta: Meta<typeof Cascader> = {
+  title: '表单与输入 · Form/Cascader',
+  component: Cascader,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '级联选择 — 多级联动(地区 / 分类 / 文件夹路径),多列面板,叶子触发 onChange(可改 changeOnSelect 为每级触发)。等价 antd `Cascader`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Cascader>;
+
+const regions: CascaderOption[] = [
+  {
+    value: 'cn',
+    label: '中国',
+    children: [
+      {
+        value: 'zj',
+        label: '浙江',
+        children: [
+          { value: 'hz', label: '杭州' },
+          { value: 'nb', label: '宁波' },
+          { value: 'wz', label: '温州' },
+        ],
+      },
+      {
+        value: 'js',
+        label: '江苏',
+        children: [
+          { value: 'nj', label: '南京' },
+          { value: 'sz', label: '苏州' },
+        ],
+      },
+      {
+        value: 'jx',
+        label: '江西',
+        disabled: true,
+        children: [{ value: 'nc', label: '南昌' }],
+      },
+    ],
+  },
+  {
+    value: 'us',
+    label: '美国',
+    children: [{ value: 'ca', label: '加州', children: [{ value: 'sf', label: '旧金山' }] }],
+  },
+];
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Cascader options={regions} placeholder="选择地区" />,
+};
+
+export const ChangeOnSelect: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState<string[]>([]);
+    return (
+      <div className="flex flex-col gap-2">
+        <Cascader
+          options={regions}
+          changeOnSelect
+          value={v}
+          onChange={setV}
+        />
+        <div className="text-xs text-muted-foreground">
+          value: {v.length ? v.join(' / ') : '(空)'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Controlled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState<string[]>(['cn', 'zj', 'hz']);
+    return (
+      <div className="flex items-center gap-3">
+        <Cascader options={regions} value={v} onChange={setV} />
+        <button
+          type="button"
+          onClick={() => setV([])}
+          className="text-xs text-primary hover:underline"
+        >
+          清空
+        </button>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Cascader disabled options={regions} defaultValue={['cn', 'zj', 'hz']} />
+  ),
+};

package/src/components/cascader/cascader.tsx

@@ -0,0 +1,198 @@
+import * as React from 'react';
+import { ChevronDown, ChevronRight } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/popover/popover';
+
+export interface CascaderOption {
+  /** 级联节点 value(同级 value 必须唯一)。 */
+  value: string;
+  /** 级联节点 label。 */
+  label: React.ReactNode;
+  /** 子选项 — 无 children 视为叶子。 */
+  children?: CascaderOption[];
+  /** 禁用此项。 */
+  disabled?: boolean;
+}
+
+export interface CascaderProps {
+  /** 级联选项树(antd `options` 并集)。 */
+  options: CascaderOption[];
+  /** 受控值(每层 value 数组)。 */
+  value?: string[];
+  /** uncontrolled 初值。 */
+  defaultValue?: string[];
+  /** 值变化回调 — 触发条件:点选叶子节点或显式 changeOnSelect。 */
+  onChange?: (value: string[], selectedOptions: CascaderOption[]) => void;
+  /**
+   * 每选中一级即触发 onChange(antd `changeOnSelect` 并集) — 默认仅选叶子触发。
+   * @default false
+   */
+  changeOnSelect?: boolean;
+  /**
+   * 占位文本。
+   * @default "请选择"
+   */
+  placeholder?: string;
+  /**
+   * 路径展示的分隔符。
+   * @default " / "
+   */
+  separator?: string;
+  /** 整体禁用。 */
+  disabled?: boolean;
+  /**
+   * 触发器 className(给外层 Button)。
+   */
+  className?: string;
+  /**
+   * 触发器尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+function findPath(
+  options: CascaderOption[],
+  value: string[],
+): CascaderOption[] {
+  const path: CascaderOption[] = [];
+  let cursor: CascaderOption[] | undefined = options;
+  for (const v of value) {
+    const found: CascaderOption | undefined = cursor?.find((o) => o.value === v);
+    if (!found) break;
+    path.push(found);
+    cursor = found.children;
+  }
+  return path;
+}
+
+/**
+ * 级联选择 — antd 独有补足。**等价 antd `Cascader`**。多级联动选择(地区 / 分类 / 组织架构),
+ * 选项树由 `options.children` 表达;点击触发器弹出多列面板,**叶子触发 onChange**(可改 `changeOnSelect` 为每级触发)。
+ */
+const Cascader = React.forwardRef<HTMLButtonElement, CascaderProps>(
+  (
+    {
+      options,
+      value,
+      defaultValue,
+      onChange,
+      changeOnSelect = false,
+      placeholder = '请选择',
+      separator = ' / ',
+      disabled = false,
+      className,
+      size = 'default',
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<string[]>(defaultValue ?? []);
+    const current = isControlled ? value! : internal;
+
+    const [open, setOpen] = React.useState(false);
+    const [activePath, setActivePath] = React.useState<string[]>(current);
+
+    React.useEffect(() => {
+      if (open) setActivePath(current);
+    }, [open, current]);
+
+    const selectedPath = findPath(options, current);
+
+    const handleSelect = (level: number, opt: CascaderOption) => {
+      if (opt.disabled) return;
+      const next = [...activePath.slice(0, level), opt.value];
+      setActivePath(next);
+      const hasChildren = !!opt.children && opt.children.length > 0;
+      if (!hasChildren || changeOnSelect) {
+        const path = findPath(options, next);
+        if (!isControlled) setInternal(next);
+        onChange?.(next, path);
+        if (!hasChildren) setOpen(false);
+      }
+    };
+
+    // Render columns based on activePath
+    const columns: CascaderOption[][] = [options];
+    let cursor: CascaderOption[] | undefined = options;
+    for (const v of activePath) {
+      const found: CascaderOption | undefined = cursor?.find((o) => o.value === v);
+      if (found?.children && found.children.length > 0) {
+        columns.push(found.children);
+        cursor = found.children;
+      } else break;
+    }
+
+    const display =
+      selectedPath.length > 0
+        ? selectedPath.map((o) => o.label).join(separator)
+        : '';
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            type="button"
+            variant="outline"
+            size={size}
+            disabled={disabled}
+            className={cn(
+              'min-w-[200px] justify-between font-normal',
+              !display && 'text-muted-foreground',
+              className,
+            )}
+          >
+            <span className="truncate">{display || placeholder}</span>
+            <ChevronDown className="ml-2 size-4 shrink-0 opacity-50" />
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="flex w-auto p-0" align="start">
+          {columns.map((col, level) => (
+            <ul
+              key={level}
+              role="listbox"
+              className={cn(
+                'min-w-[160px] max-h-72 overflow-auto py-1 text-sm',
+                level > 0 && 'border-l',
+              )}
+            >
+              {col.map((opt) => {
+                const isActive = activePath[level] === opt.value;
+                const hasChildren = !!opt.children && opt.children.length > 0;
+                return (
+                  <li
+                    key={opt.value}
+                    role="option"
+                    aria-selected={isActive}
+                    onClick={() => handleSelect(level, opt)}
+                    className={cn(
+                      'flex cursor-pointer items-center justify-between gap-2 px-3 py-1.5',
+                      !opt.disabled && 'hover:bg-accent',
+                      isActive && !opt.disabled && 'bg-accent text-accent-foreground',
+                      opt.disabled && 'cursor-not-allowed opacity-50',
+                    )}
+                  >
+                    <span className="truncate">{opt.label}</span>
+                    {hasChildren ? (
+                      <ChevronRight className="size-3.5 shrink-0 opacity-60" />
+                    ) : null}
+                  </li>
+                );
+              })}
+            </ul>
+          ))}
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);
+Cascader.displayName = 'Cascader';
+
+export { Cascader };