@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/toggle-group/index.tsx

@@ -0,0 +1,167 @@
+/**
+ * 切换按钮组 ToggleGroup
+ *
+ * 一组互斥或多选的切换按钮，基于 Radix ToggleGroup 原语。
+ *
+ * @when
+ * - 工具栏的对齐方式切换（左 / 中 / 右）
+ * - 视图模式组（网格 / 列表 / 看板）
+ * - 筛选条件快速切换
+ */
+'use client';
+
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+import { ToggleGroup as ToggleGroupPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { toggleVariants } from '@/components/toggle';
+
+const ToggleGroupContext = React.createContext<
+  VariantProps<typeof toggleVariants> & {
+    spacing?: number;
+    orientation?: 'horizontal' | 'vertical';
+  }
+>({
+  size: 'default',
+  variant: 'default',
+  spacing: 2,
+  orientation: 'horizontal',
+});
+
+type ToggleGroupRootProps = React.ComponentProps<
+  typeof ToggleGroupPrimitive.Root
+>;
+
+interface ToggleGroupCommonProps extends VariantProps<typeof toggleVariants> {
+  /** 是否禁用整组。 @default false */
+  disabled?: boolean;
+  /** 文本方向。 @default 'ltr' */
+  dir?: 'ltr' | 'rtl';
+  /** 使用方向键到达边界时是否循环。 @default true */
+  loop?: boolean;
+  /** 按钮间屏距（映射为 CSS 变量 `--gap`）。 @default 2 */
+  spacing?: number;
+  /** 排列方向。 @default 'horizontal' */
+  orientation?: 'horizontal' | 'vertical';
+}
+
+/** ToggleGroup 单选模式 Props。 */
+export interface ToggleGroupSingleProps extends ToggleGroupCommonProps {
+  /** 单选 / 多选模式。 */
+  type: 'single';
+  /** 受控当前选中项。 */
+  value?: string;
+  /** 非受控初始选中项。 */
+  defaultValue?: string;
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项的 value；反选后为 ""
+   */
+  onValueChange?: (value: string) => void;
+}
+
+/** ToggleGroup 多选模式 Props。 */
+export interface ToggleGroupMultipleProps extends ToggleGroupCommonProps {
+  /** 单选 / 多选模式。 */
+  type: 'multiple';
+  /** 受控当前选中项集合。 */
+  value?: string[];
+  /** 非受控初始选中项集合。 */
+  defaultValue?: string[];
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项 value 集合
+   */
+  onValueChange?: (value: string[]) => void;
+}
+
+export type ToggleGroupProps = (
+  | ToggleGroupSingleProps
+  | ToggleGroupMultipleProps
+) &
+  Omit<
+    ToggleGroupRootProps,
+    | keyof ToggleGroupCommonProps
+    | 'type'
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+  >;
+
+function ToggleGroup({
+  className,
+  variant,
+  size,
+  spacing = 2,
+  orientation = 'horizontal',
+  children,
+  ...props
+}: ToggleGroupProps) {
+  return (
+    <ToggleGroupPrimitive.Root
+      data-slot="toggle-group"
+      data-variant={variant}
+      data-size={size}
+      data-spacing={spacing}
+      data-orientation={orientation}
+      style={{ '--gap': spacing } as React.CSSProperties}
+      className={cn(
+        // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- dynamic gap via CSS var and responsive radius clamping not tokenizable.
+        'group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-md data-[size=sm]:rounded-md data-[orientation=vertical]:flex-col data-[orientation=vertical]:items-stretch',
+        className,
+      )}
+      {...(props as ToggleGroupRootProps)}
+    >
+      <ToggleGroupContext.Provider
+        value={{ variant, size, spacing, orientation }}
+      >
+        {children}
+      </ToggleGroupContext.Provider>
+    </ToggleGroupPrimitive.Root>
+  );
+}
+
+export interface ToggleGroupItemProps
+  extends Omit<
+      React.ComponentProps<typeof ToggleGroupPrimitive.Item>,
+      'value' | 'disabled'
+    >,
+    VariantProps<typeof toggleVariants> {
+  /** 当前项的唯一值，必填。 */
+  value: string;
+  /** 是否禁用当前项。 @default false */
+  disabled?: boolean;
+}
+
+function ToggleGroupItem({
+  className,
+  children,
+  variant = 'default',
+  size = 'default',
+  ...props
+}: ToggleGroupItemProps) {
+  const context = React.useContext(ToggleGroupContext);
+
+  return (
+    <ToggleGroupPrimitive.Item
+      data-slot="toggle-group-item"
+      data-variant={context.variant || variant}
+      data-size={context.size || size}
+      data-spacing={context.spacing}
+      className={cn(
+        'shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-[orientation=horizontal]/toggle-group:data-[spacing=0]:first:rounded-l-md group-data-[orientation=vertical]/toggle-group:data-[spacing=0]:first:rounded-t-md group-data-[orientation=horizontal]/toggle-group:data-[spacing=0]:last:rounded-r-md group-data-[orientation=vertical]/toggle-group:data-[spacing=0]:last:rounded-b-md group-data-[orientation=horizontal]/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-[orientation=vertical]/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-[orientation=horizontal]/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-[orientation=vertical]/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t',
+        toggleVariants({
+          variant: context.variant || variant,
+          size: context.size || size,
+        }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </ToggleGroupPrimitive.Item>
+  );
+}
+
+export { ToggleGroup, ToggleGroupItem };

package/src/components/toggle-group/meta.md

@@ -0,0 +1,141 @@
+# ToggleGroupSingle
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+切换按钮组 ToggleGroup
+一组互斥或多选的切换按钮，基于 Radix ToggleGroup 原语。
+
+## 使用场景
+
+- 工具栏的对齐方式切换（左 / 中 / 右）
+- 视图模式组（网格 / 列表 / 看板）
+- 筛选条件快速切换
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `type` | `'single'` | – | ✓ | 单选 / 多选模式。 |
+| `value` | `string` | – | – | 受控当前选中项。 |
+| `defaultValue` | `string` | – | – | 非受控初始选中项。 |
+| `onValueChange` | `(value: string) => void` | – | – | 选中项变化回调。 |
+| `type` | `'multiple'` | – | ✓ | 单选 / 多选模式。 |
+| `value` | `string[]` | – | – | 受控当前选中项集合。 |
+| `defaultValue` | `string[]` | – | – | 非受控初始选中项集合。 |
+| `onValueChange` | `(value: string[]) => void` | – | – | 选中项变化回调。 |
+| `value` | `string` | – | ✓ | 当前项的唯一值，必填。 |
+| `disabled` | `boolean` | `false` | – | 是否禁用当前项。 |
+
+## 示例
+
+### Single
+
+单选模式，同一时间只有一个选中。
+
+```tsx
+<ToggleGroup type="single" defaultValue="center">
+  <ToggleGroupItem value="left" aria-label="左对齐">
+    <AlignLeftIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="center" aria-label="居中">
+    <AlignCenterIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="right" aria-label="右对齐">
+    <AlignRightIcon />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Multiple
+
+多选模式，允许同时选中多个。
+
+```tsx
+<ToggleGroup type="multiple" defaultValue={['bold', 'italic']}>
+  <ToggleGroupItem value="bold" aria-label="加粗">
+    <BoldIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="italic" aria-label="斜体">
+    <ItalicIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="underline" aria-label="下划线">
+    <UnderlineIcon />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Outline
+
+使用 `variant="outline"` 显示带边框的切换组。
+
+```tsx
+<ToggleGroup type="single" variant="outline" defaultValue="left">
+  <ToggleGroupItem value="left" aria-label="左对齐">
+    <AlignLeftIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="center" aria-label="居中">
+    <AlignCenterIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="right" aria-label="右对齐">
+    <AlignRightIcon />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+### NoSpacing
+
+`spacing={0}` 时按钮无间距紧贴，视觉类似 ButtonGroup。
+
+```tsx
+<ToggleGroup
+  type="single"
+  variant="outline"
+  spacing={0}
+  defaultValue="left"
+>
+  <ToggleGroupItem value="left" aria-label="左对齐">
+    <AlignLeftIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="center" aria-label="居中">
+    <AlignCenterIcon />
+  </ToggleGroupItem>
+  <ToggleGroupItem value="right" aria-label="右对齐">
+    <AlignRightIcon />
+  </ToggleGroupItem>
+</ToggleGroup>
+```
+
+### Sizes
+
+支持 `sm`、`default`、`lg` 三种尺寸。
+
+```tsx
+<div className="flex flex-col items-start gap-4">
+  <ToggleGroup type="single" size="sm" defaultValue="left">
+    <ToggleGroupItem value="left" aria-label="左对齐">
+      <AlignLeftIcon />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="center" aria-label="居中">
+      <AlignCenterIcon />
+    </ToggleGroupItem>
+  </ToggleGroup>
+  <ToggleGroup type="single" defaultValue="left">
+    <ToggleGroupItem value="left" aria-label="左对齐">
+      <AlignLeftIcon />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="center" aria-label="居中">
+      <AlignCenterIcon />
+    </ToggleGroupItem>
+  </ToggleGroup>
+  <ToggleGroup type="single" size="lg" defaultValue="left">
+    <ToggleGroupItem value="left" aria-label="左对齐">
+      <AlignLeftIcon />
+    </ToggleGroupItem>
+    <ToggleGroupItem value="center" aria-label="居中">
+      <AlignCenterIcon />
+    </ToggleGroupItem>
+  </ToggleGroup>
+</div>
+```

package/src/components/toggle-group/stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  BoldIcon,
+  ItalicIcon,
+  UnderlineIcon,
+  AlignLeftIcon,
+  AlignCenterIcon,
+  AlignRightIcon,
+} from 'lucide-react';
+import { ToggleGroup, ToggleGroupItem } from './index';
+
+const meta = {
+  title: '数据录入 · Data Entry/ToggleGroup 切换按钮组',
+  component: ToggleGroup,
+  tags: ['autodocs'],
+} satisfies Meta<typeof ToggleGroup>;
+export default meta;
+
+type Story = StoryObj<typeof ToggleGroup>;
+
+/** 单选模式，同一时间只有一个选中。 */
+export const Single: Story = {
+  render: () => (
+    <ToggleGroup type="single" defaultValue="center">
+      <ToggleGroupItem value="left" aria-label="左对齐">
+        <AlignLeftIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="center" aria-label="居中">
+        <AlignCenterIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="right" aria-label="右对齐">
+        <AlignRightIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+/** 多选模式，允许同时选中多个。 */
+export const Multiple: Story = {
+  render: () => (
+    <ToggleGroup type="multiple" defaultValue={['bold', 'italic']}>
+      <ToggleGroupItem value="bold" aria-label="加粗">
+        <BoldIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="italic" aria-label="斜体">
+        <ItalicIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="underline" aria-label="下划线">
+        <UnderlineIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+/** 使用 `variant="outline"` 显示带边框的切换组。 */
+export const Outline: Story = {
+  render: () => (
+    <ToggleGroup type="single" variant="outline" defaultValue="left">
+      <ToggleGroupItem value="left" aria-label="左对齐">
+        <AlignLeftIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="center" aria-label="居中">
+        <AlignCenterIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="right" aria-label="右对齐">
+        <AlignRightIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+/** `spacing={0}` 时按钮无间距紧贴，视觉类似 ButtonGroup。 */
+export const NoSpacing: Story = {
+  render: () => (
+    <ToggleGroup
+      type="single"
+      variant="outline"
+      spacing={0}
+      defaultValue="left"
+    >
+      <ToggleGroupItem value="left" aria-label="左对齐">
+        <AlignLeftIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="center" aria-label="居中">
+        <AlignCenterIcon />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="right" aria-label="右对齐">
+        <AlignRightIcon />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+/** 支持 `sm`、`default`、`lg` 三种尺寸。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col items-start gap-4">
+      <ToggleGroup type="single" size="sm" defaultValue="left">
+        <ToggleGroupItem value="left" aria-label="左对齐">
+          <AlignLeftIcon />
+        </ToggleGroupItem>
+        <ToggleGroupItem value="center" aria-label="居中">
+          <AlignCenterIcon />
+        </ToggleGroupItem>
+      </ToggleGroup>
+      <ToggleGroup type="single" defaultValue="left">
+        <ToggleGroupItem value="left" aria-label="左对齐">
+          <AlignLeftIcon />
+        </ToggleGroupItem>
+        <ToggleGroupItem value="center" aria-label="居中">
+          <AlignCenterIcon />
+        </ToggleGroupItem>
+      </ToggleGroup>
+      <ToggleGroup type="single" size="lg" defaultValue="left">
+        <ToggleGroupItem value="left" aria-label="左对齐">
+          <AlignLeftIcon />
+        </ToggleGroupItem>
+        <ToggleGroupItem value="center" aria-label="居中">
+          <AlignCenterIcon />
+        </ToggleGroupItem>
+      </ToggleGroup>
+    </div>
+  ),
+};

package/src/components/tooltip/index.tsx

@@ -0,0 +1,144 @@
+/**
+ * 提示 Tooltip
+ *
+ * 悬停或聚焦时展示简短提示文字，可选两种视觉变体（亮底 / 反色）。
+ *
+ * @when
+ * - 图标按钮需要文字解释
+ * - 截断文本悬停展示完整内容
+ * - 为操作提供额外上下文信息
+ *
+ * 组合结构：TooltipProvider > Tooltip > TooltipTrigger + TooltipContent (> TooltipArrow?)
+ */
+
+'use client';
+
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+export interface TooltipProps
+  extends Omit<
+    React.ComponentProps<typeof TooltipPrimitive.Root>,
+    | 'open'
+    | 'defaultOpen'
+    | 'onOpenChange'
+    | 'delayDuration'
+    | 'disableHoverableContent'
+  > {
+  /** 受控显示状态。 */
+  open?: boolean;
+  /** 非受控初始显示状态。 @default false */
+  defaultOpen?: boolean;
+  /**
+   * 显示 / 关闭状态变化回调。
+   * @param open 当前是否显示
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** 悬停多久后打开（毫秒）。默认跟随 Provider 设置。 */
+  delayDuration?: number;
+  /** 是否禁用鼠标进入 Tooltip 内保持显示。 @default false */
+  disableHoverableContent?: boolean;
+}
+
+function Tooltip({ ...props }: TooltipProps) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+const tooltipContentVariants = cva(
+  'group/tooltip-content z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded-md px-3 py-1.5 text-xs shadow-md has-data-[slot=kbd]:pr-1.5 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-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 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',
+  {
+    variants: {
+      variant: {
+        default: 'border border-border bg-popover text-popover-foreground',
+        inverse: 'bg-foreground text-background',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+);
+
+export interface TooltipContentProps
+  extends React.ComponentProps<typeof TooltipPrimitive.Content>,
+    VariantProps<typeof tooltipContentVariants> {
+  /** 视觉变体：default = 亮底；inverse = 反色（深底白字）。 @default 'default' */
+  variant?: 'default' | 'inverse';
+  /** 浮层渲染容器，透传给 Portal。 @default document.body */
+  container?: HTMLElement | null;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 4,
+  variant = 'default',
+  container,
+  children,
+  ...props
+}: TooltipContentProps) {
+  return (
+    <TooltipPrimitive.Portal container={container}>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        data-variant={variant}
+        sideOffset={sideOffset}
+        className={cn(tooltipContentVariants({ variant }), className)}
+        {...props}
+      >
+        {children}
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+function TooltipArrow({
+  className,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Arrow>) {
+  // ant Balloon 风格：方块 rotate-45 后半截嵌入 Content、半截露出。
+  // Radix Popper 已根据 side 为外层 wrapper 自动旋转（top: 0 / bottom: 180° / left: -90° / right: 90°），
+  // 所以 SVG 本地坐标系中“朝外露出的两条边”在四个方向下始终是 right + bottom——
+  // 不需要再按 data-side 切换 border，否则在 bottom/left/right 时会拼错边，表现为“箭头反了”。
+  return (
+    <TooltipPrimitive.Arrow
+      data-slot="tooltip-arrow"
+      width={10}
+      height={10}
+      className={cn(
+        'block size-2 -translate-y-1/2 rotate-45 border-0 border-r border-b border-border bg-popover fill-popover',
+        'group-data-[variant=inverse]/tooltip-content:border-foreground group-data-[variant=inverse]/tooltip-content:bg-foreground group-data-[variant=inverse]/tooltip-content:fill-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  tooltipContentVariants,
+};