@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/accordion/index.tsx

@@ -0,0 +1,139 @@
+/**
+ * 手风琴 Accordion
+ *
+ * 可展开的内容分组，支持单项 / 多项展开模式，基于 Radix Accordion 原语。
+ *
+ * @when
+ * - FAQ 问答列表
+ * - 设置页的分组展开
+ * - 多步骤表单的折叠分区
+ */
+import * as React from 'react';
+import { Accordion as AccordionPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { ChevronDownIcon } from 'lucide-react';
+
+type AccordionRootProps = React.ComponentProps<typeof AccordionPrimitive.Root>;
+
+interface AccordionCommonProps {
+  /** 是否允许点击已展开项将其收起（仅 type='single' 生效）。 @default false */
+  collapsible?: boolean;
+  /** 禁用整个手风琴。 @default false */
+  disabled?: boolean;
+  /** 文字方向。 */
+  dir?: 'ltr' | 'rtl';
+  /** 排列方向。 @default 'vertical' */
+  orientation?: 'horizontal' | 'vertical';
+}
+
+export interface AccordionSingleProps extends AccordionCommonProps {
+  /** 折叠模式：'single' 最多展开一项 / 'multiple' 可同时展开多项。 */
+  type: 'single';
+  /** 受控展开项的 value。 */
+  value?: string;
+  /** 非受控初始展开项的 value。 */
+  defaultValue?: string;
+  /**
+   * 展开项变化回调。
+   * @param value 当前展开项的 value（允许收起时为空字符串）
+   */
+  onValueChange?: (value: string) => void;
+}
+
+export interface AccordionMultipleProps extends AccordionCommonProps {
+  /** 折叠模式：'single' 最多展开一项 / 'multiple' 可同时展开多项。 */
+  type: 'multiple';
+  /** 受控展开项的 value 列表。 */
+  value?: string[];
+  /** 非受控初始展开项的 value 列表。 */
+  defaultValue?: string[];
+  /**
+   * 展开项变化回调。
+   * @param value 当前全部展开项的 value 列表
+   */
+  onValueChange?: (value: string[]) => void;
+}
+
+export type AccordionProps = (AccordionSingleProps | AccordionMultipleProps) &
+  Omit<
+    AccordionRootProps,
+    | keyof AccordionCommonProps
+    | 'type'
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+  >;
+
+function Accordion({ className, ...props }: AccordionProps) {
+  return (
+    <AccordionPrimitive.Root
+      data-slot="accordion"
+      className={cn('flex w-full flex-col', className)}
+      {...(props as AccordionRootProps)}
+    />
+  );
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn('not-last:mb-0.5', className)}
+      {...props}
+    />
+  );
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          'group/accordion-trigger flex h-10 w-full cursor-pointer items-center gap-2 rounded-md bg-muted px-3 text-left text-xs font-medium text-foreground transition-colors outline-none hover:bg-muted-foreground/10 focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:text-muted-foreground disabled:opacity-50',
+          className,
+        )}
+        {...props}
+      >
+        <ChevronDownIcon
+          data-slot="accordion-trigger-icon"
+          className="pointer-events-none size-3 shrink-0 -rotate-90 text-muted-foreground transition-transform duration-200 group-aria-expanded/accordion-trigger:rotate-0"
+        />
+        {children}
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  );
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="overflow-hidden text-sm data-[state=open]:animate-accordion-down data-[state=closed]:animate-accordion-up"
+      {...props}
+    >
+      <div
+        className={cn(
+          'h-(--radix-accordion-content-height) pt-2 pr-3 pb-3 pl-8 text-muted-foreground [&_a]:text-primary [&_a]:hover:text-primary/80 [&_p:not(:last-child)]:mb-4',
+          className,
+        )}
+      >
+        {children}
+      </div>
+    </AccordionPrimitive.Content>
+  );
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

package/src/components/accordion/meta.md

@@ -0,0 +1,162 @@
+# AccordionSingle
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+手风琴 Accordion
+可展开的内容分组，支持单项 / 多项展开模式，基于 Radix Accordion 原语。
+
+## 使用场景
+
+- FAQ 问答列表
+- 设置页的分组展开
+- 多步骤表单的折叠分区
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `type` | `'single'` | – | ✓ | 折叠模式：'single' 最多展开一项 / 'multiple' 可同时展开多项。 |
+| `value` | `string` | – | – | 受控展开项的 value。 |
+| `defaultValue` | `string` | – | – | 非受控初始展开项的 value。 |
+| `onValueChange` | `(value: string) => void` | – | – | 展开项变化回调。 |
+| `type` | `'multiple'` | – | ✓ | 折叠模式：'single' 最多展开一项 / 'multiple' 可同时展开多项。 |
+| `value` | `string[]` | – | – | 受控展开项的 value 列表。 |
+| `defaultValue` | `string[]` | – | – | 非受控初始展开项的 value 列表。 |
+| `onValueChange` | `(value: string[]) => void` | – | – | 展开项变化回调。 |
+
+## 示例
+
+### Single
+
+手风琴模式（accordion），一次只能展开一个面板。
+
+```tsx
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="item-1">
+    <AccordionTrigger>什么是促销活动？</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        促销活动是由平台发起的营销活动，参与即可在促销期间销售产品并获取收益。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>如何参与？</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        选择需要参与促销的商品，设置库存量即可加入活动。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-3">
+    <AccordionTrigger>为什么不能提交更高价格？</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        促销要求设定一定的折扣力度以确保吸引消费者。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Multiple
+
+多选模式（multiple），可以同时展开多个面板。
+
+```tsx
+<Accordion
+  type="multiple"
+  defaultValue={['item-1', 'item-2']}
+  className="w-full"
+>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>基本信息</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        填写您的姓名、邮箱和联系电话。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>安全设置</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        管理密码、两步验证和安全问题。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-3">
+    <AccordionTrigger>通知偏好</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        设置邮件通知、短信通知和推送通知。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### DefaultOpen
+
+默认展开指定面板。
+
+```tsx
+<Accordion
+  type="single"
+  collapsible
+  defaultValue="item-2"
+  className="w-full"
+>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>第一项</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">第一项的内容。</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>第二项（默认展开）</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        此面板初始状态即为展开。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-3">
+    <AccordionTrigger>第三项</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">第三项的内容。</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Disabled
+
+禁用某个面板，不可交互。
+
+```tsx
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="item-1">
+    <AccordionTrigger>可操作面板</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">
+        此面板可正常展开/折叠。
+      </p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2" disabled>
+    <AccordionTrigger>已禁用面板</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">此内容不可见。</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-3">
+    <AccordionTrigger>另一个可操作面板</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-xs text-muted-foreground">正常内容。</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/src/components/accordion/stories.tsx

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from './index';
+
+const meta = {
+  title: '数据展示 · Data Display/Accordion 折叠面板',
+  component: Accordion,
+  tags: ['autodocs'],
+} satisfies Meta<typeof Accordion>;
+export default meta;
+
+type Story = StoryObj<typeof Accordion>;
+
+/** 手风琴模式（accordion），一次只能展开一个面板。 */
+export const Single: Story = {
+  render: () => (
+    <Accordion type="single" collapsible className="w-full">
+      <AccordionItem value="item-1">
+        <AccordionTrigger>什么是促销活动？</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            促销活动是由平台发起的营销活动，参与即可在促销期间销售产品并获取收益。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>如何参与？</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            选择需要参与促销的商品，设置库存量即可加入活动。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>为什么不能提交更高价格？</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            促销要求设定一定的折扣力度以确保吸引消费者。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+};
+
+/** 多选模式（multiple），可以同时展开多个面板。 */
+export const Multiple: Story = {
+  render: () => (
+    <Accordion
+      type="multiple"
+      defaultValue={['item-1', 'item-2']}
+      className="w-full"
+    >
+      <AccordionItem value="item-1">
+        <AccordionTrigger>基本信息</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            填写您的姓名、邮箱和联系电话。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>安全设置</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            管理密码、两步验证和安全问题。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>通知偏好</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            设置邮件通知、短信通知和推送通知。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+};
+
+/** 默认展开指定面板。 */
+export const DefaultOpen: Story = {
+  render: () => (
+    <Accordion
+      type="single"
+      collapsible
+      defaultValue="item-2"
+      className="w-full"
+    >
+      <AccordionItem value="item-1">
+        <AccordionTrigger>第一项</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">第一项的内容。</p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2">
+        <AccordionTrigger>第二项（默认展开）</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            此面板初始状态即为展开。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>第三项</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">第三项的内容。</p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+};
+
+/** 禁用某个面板，不可交互。 */
+export const Disabled: Story = {
+  render: () => (
+    <Accordion type="single" collapsible className="w-full">
+      <AccordionItem value="item-1">
+        <AccordionTrigger>可操作面板</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">
+            此面板可正常展开/折叠。
+          </p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-2" disabled>
+        <AccordionTrigger>已禁用面板</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">此内容不可见。</p>
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="item-3">
+        <AccordionTrigger>另一个可操作面板</AccordionTrigger>
+        <AccordionContent>
+          <p className="text-xs text-muted-foreground">正常内容。</p>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  ),
+};

package/src/components/affix/index.tsx

@@ -0,0 +1,149 @@
+/**
+ * 固钉 Affix
+ *
+ * 将元素固定在可视区域的指定位置（吸顶 / 吸底）。
+ *
+ * @when
+ * - 长页面中需要操作栏始终可见
+ * - 表格 / 列表页顶部筛选栏吸顶
+ * - 返回顶部按钮吸底
+ */
+'use client';
+
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+interface AffixProps extends React.ComponentProps<'div'> {
+  /**
+   * 距离视口顶部指定偏移量后吸顶（px）。
+   * @default 0
+   */
+  offsetTop?: number;
+  /**
+   * 距离视口底部指定偏移量后吸底（px）— 与 `offsetTop` 互斥。
+   */
+  offsetBottom?: number;
+  /**
+   * 滚动容器 — 默认 `window`。传入自定义容器时使用 `position: sticky`。
+   * @default () => window
+   */
+  container?: () => HTMLElement | Window;
+  /**
+   * 吸附状态变化回调。
+   */
+  onAffixChange?: (affixed: boolean) => void;
+}
+
+const isWindow = (target: HTMLElement | Window): target is Window =>
+  target === window;
+
+function Affix({
+  offsetTop = 0,
+  offsetBottom,
+  container,
+  onAffixChange,
+  className,
+  style,
+  children,
+  ...props
+}: AffixProps) {
+  const wrapperRef = React.useRef<HTMLDivElement>(null);
+  const [affixed, setAffixed] = React.useState(false);
+  const [size, setSize] = React.useState<{ w: number; h: number }>({
+    w: 0,
+    h: 0,
+  });
+
+  React.useEffect(() => {
+    const el = wrapperRef.current;
+    if (!el) return;
+
+    const target = container ? container() : window;
+    const useCustomContainer = !isWindow(target);
+
+    const compute = () => {
+      const rect = el.getBoundingClientRect();
+      const useBottom = typeof offsetBottom === 'number';
+
+      let top: number;
+      let viewport: number;
+      if (useCustomContainer) {
+        const cRect = (target as HTMLElement).getBoundingClientRect();
+        top = rect.top - cRect.top;
+        viewport = cRect.height;
+      } else {
+        top = rect.top;
+        viewport = window.innerHeight;
+      }
+
+      const bottom = viewport - (top + rect.height);
+      const shouldAffix = useBottom
+        ? bottom < (offsetBottom ?? 0)
+        : top < offsetTop;
+
+      if (shouldAffix !== affixed) {
+        setAffixed(shouldAffix);
+        onAffixChange?.(shouldAffix);
+      }
+      setSize({ w: rect.width, h: rect.height });
+    };
+
+    compute();
+    target.addEventListener('scroll', compute, { passive: true });
+    window.addEventListener('resize', compute);
+    return () => {
+      target.removeEventListener('scroll', compute);
+      window.removeEventListener('resize', compute);
+    };
+  }, [affixed, offsetBottom, offsetTop, onAffixChange, container]);
+
+  // Container 模式：position: sticky
+  if (container) {
+    const stickyStyle: React.CSSProperties = {
+      position: 'sticky',
+      top: typeof offsetBottom === 'number' ? undefined : offsetTop,
+      bottom: typeof offsetBottom === 'number' ? offsetBottom : undefined,
+      zIndex: 10,
+      ...style,
+    };
+    return (
+      <div
+        ref={wrapperRef}
+        data-slot="affix"
+        style={stickyStyle}
+        className={cn('transition-shadow', affixed && 'shadow-sm', className)}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  }
+
+  // Window 模式：position: fixed + 占位高度
+  const fixedStyle: React.CSSProperties | undefined = affixed
+    ? {
+        position: 'fixed',
+        top: typeof offsetBottom === 'number' ? undefined : offsetTop,
+        bottom: typeof offsetBottom === 'number' ? offsetBottom : undefined,
+        width: size.w,
+        zIndex: 10,
+      }
+    : undefined;
+
+  return (
+    <div
+      ref={wrapperRef}
+      data-slot="affix"
+      style={{ ...style, height: affixed ? size.h : undefined }}
+      className={className}
+    >
+      <div style={fixedStyle} className={cn(affixed && 'shadow-sm')} {...props}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export { Affix };
+export type { AffixProps };

package/src/components/affix/meta.md

@@ -0,0 +1,23 @@
+# Affix
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+固钉 Affix
+将元素固定在可视区域的指定位置（吸顶 / 吸底）。
+
+## 使用场景
+
+- 长页面中需要操作栏始终可见
+- 表格 / 列表页顶部筛选栏吸顶
+- 返回顶部按钮吸底
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `offsetTop` | `number` | `0` | – | 距离视口顶部指定偏移量后吸顶（px）。 |
+| `offsetBottom` | `number` | – | – | 距离视口底部指定偏移量后吸底（px）— 与 `offsetTop` 互斥。 |
+| `container` | `() => HTMLElement \| Window` | `() => window` | – | 滚动容器 — 默认 `window`。传入自定义容器时使用 `position: sticky`。 |
+| `onAffixChange` | `(affixed: boolean) => void` | – | – | 吸附状态变化回调。 |

package/src/components/affix/stories.tsx

@@ -0,0 +1,70 @@
+/* eslint-disable teamix-evo/no-arbitrary-tw-value -- Storybook demo containers need fixed pixel heights to showcase scroll-affix behavior. */
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Affix } from '.';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Affix> = {
+  title: '导航 · Navigation/Affix 固钉',
+  component: Affix,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Affix>;
+
+/** 滚动容器内吸顶 — 向下滚动触发。 */
+export const Default: Story = {
+  render: () => {
+    const ref = React.useRef<HTMLDivElement>(null);
+    return (
+      <div
+        ref={ref}
+        className="relative h-[400px] overflow-auto rounded-md border border-border p-4"
+      >
+        <p className="mb-3 text-sm text-muted-foreground">
+          ↓ 向下滚动查看吸顶效果
+        </p>
+        <div className="h-40 rounded-md border border-border bg-card p-4 text-sm text-muted-foreground">
+          占位区域
+        </div>
+        <div className="mt-3" />
+        <Affix offsetTop={0} container={() => ref.current!}>
+          <div className="rounded-md border border-border bg-background p-3 shadow-sm">
+            <Button>吸顶按钮</Button>
+          </div>
+        </Affix>
+        <div className="h-[800px] rounded-md border border-border bg-card p-4 mt-3 text-sm text-muted-foreground">
+          长内容区域
+        </div>
+      </div>
+    );
+  },
+};
+
+/** 吸底 — 滚动时固定在容器底部。 */
+export const Bottom: Story = {
+  render: () => {
+    const ref = React.useRef<HTMLDivElement>(null);
+    return (
+      <div
+        ref={ref}
+        className="relative h-[400px] overflow-auto rounded-md border border-border p-4"
+      >
+        <div className="h-[500px] rounded-md border border-border bg-card p-4 text-sm text-muted-foreground">
+          向下滚动
+        </div>
+        <div className="mt-3" />
+        <Affix offsetBottom={16} container={() => ref.current!}>
+          <div className="rounded-md border border-border bg-background p-3 shadow-sm">
+            <Button block>立即提交（吸底）</Button>
+          </div>
+        </Affix>
+        <div className="h-[500px] rounded-md border border-border bg-card p-4 mt-3 text-sm text-muted-foreground">
+          底部区域
+        </div>
+      </div>
+    );
+  },
+};