@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/float-button/index.tsx

@@ -0,0 +1,163 @@
+/**
+ * 悬浮按钮 FloatButton
+ *
+ * 固定在视口角落的操作按钮，用于回到顶部、客服入口、新建等高频操作。
+ *
+ * @when
+ * - 需要全局可达的快捷操作入口
+ * - 回到顶部按钮
+ * - 客服 / 反馈浮动入口
+ *
+ * 组合结构：FloatButtonGroup > FloatButton | FloatButtonBackTop
+ */
+'use client';
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ArrowUpIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+const floatButtonVariants = cva(
+  'relative inline-flex items-center justify-center transition-all shadow-lg hover:shadow-xl active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring cursor-pointer disabled:cursor-not-allowed disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        default:
+          'border border-border bg-background text-foreground hover:bg-accent',
+      },
+      shape: {
+        circle: 'rounded-full',
+        square: 'rounded-md',
+      },
+      size: {
+        default: 'size-8',
+        sm: 'size-6',
+        lg: 'size-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'primary',
+      shape: 'circle',
+      size: 'default',
+    },
+  },
+);
+
+export interface FloatButtonProps
+  extends React.ComponentProps<'button'>,
+    VariantProps<typeof floatButtonVariants> {
+  /** 按钮图标 */
+  icon?: React.ReactNode;
+  /** 右上角徽标 */
+  badge?: React.ReactNode;
+}
+
+function FloatButton({
+  icon,
+  badge,
+  variant,
+  shape,
+  size,
+  className,
+  children,
+  ...props
+}: FloatButtonProps) {
+  return (
+    <button
+      type="button"
+      data-slot="float-button"
+      data-variant={variant ?? 'primary'}
+      className={cn(floatButtonVariants({ variant, shape, size, className }))}
+      {...props}
+    >
+      {icon ?? children}
+      {badge != null && (
+        <span
+          data-slot="float-button-badge"
+          className="absolute -right-1 -top-1 flex h-5 min-w-5 items-center justify-center rounded-full bg-destructive px-1 text-xxs font-medium leading-none text-destructive-foreground"
+        >
+          {badge}
+        </span>
+      )}
+    </button>
+  );
+}
+
+// ─── FloatButtonGroup ─────────────────────────────────────────────────────────
+
+export interface FloatButtonGroupProps extends React.ComponentProps<'div'> {
+  /**
+   * 距视口右侧的距离
+   * @default 24
+   */
+  right?: number;
+  /**
+   * 距视口底部的距离
+   * @default 24
+   */
+  bottom?: number;
+}
+
+function FloatButtonGroup({
+  right = 24,
+  bottom = 24,
+  className,
+  style,
+  ...props
+}: FloatButtonGroupProps) {
+  return (
+    <div
+      data-slot="float-button-group"
+      className={cn('fixed z-40 flex flex-col items-end gap-3', className)}
+      style={{ right, bottom, ...style }}
+      {...props}
+    />
+  );
+}
+
+// ─── FloatButtonBackTop ───────────────────────────────────────────────────────
+
+export interface FloatButtonBackTopProps
+  extends Omit<FloatButtonProps, 'icon' | 'onClick'> {
+  /**
+   * 滚动超过此偏移量（px）时显示，为 0 则始终显示
+   * @default 200
+   */
+  visibilityHeight?: number;
+}
+
+function FloatButtonBackTop({
+  visibilityHeight = 200,
+  ...props
+}: FloatButtonBackTopProps) {
+  const [visible, setVisible] = React.useState(visibilityHeight === 0);
+
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const update = () => setVisible(window.scrollY > visibilityHeight);
+    update();
+    window.addEventListener('scroll', update, { passive: true });
+    return () => window.removeEventListener('scroll', update);
+  }, [visibilityHeight]);
+
+  if (!visible) return null;
+
+  return (
+    <FloatButton
+      data-slot="float-button-back-top"
+      icon={<ArrowUpIcon className="size-5" />}
+      onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}
+      aria-label="回到顶部"
+      {...props}
+    />
+  );
+}
+
+export {
+  FloatButton,
+  floatButtonVariants,
+  FloatButtonGroup,
+  FloatButtonBackTop,
+};

package/src/components/float-button/meta.md

@@ -0,0 +1,73 @@
+# FloatButton
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+悬浮按钮 FloatButton
+固定在视口角落的操作按钮，用于回到顶部、客服入口、新建等高频操作。
+
+## 使用场景
+
+- 需要全局可达的快捷操作入口
+- 回到顶部按钮
+- 客服 / 反馈浮动入口
+- 组合结构：FloatButtonGroup > FloatButton | FloatButtonBackTop
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `"primary" \| "default"` | `"primary"` | – | – |
+| `shape` | `"circle" \| "square"` | `"circle"` | – | – |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | – | – |
+| `icon` | `React.ReactNode` | – | – | 按钮图标 |
+| `badge` | `React.ReactNode` | – | – | 右上角徽标 |
+| `right` | `number` | `24` | – | 距视口右侧的距离 |
+| `bottom` | `number` | `24` | – | 距视口底部的距离 |
+| `visibilityHeight` | `number` | `200` | – | 滚动超过此偏移量（px）时显示，为 0 则始终显示 |
+
+## 示例
+
+### Group
+
+多个按钮通过 FloatButtonGroup 堆叠。
+
+```tsx
+<DemoContainer>
+  <FloatButton
+    icon={<MessageCircleIcon />}
+    aria-label="客服"
+    badge="3"
+  />
+  <FloatButton
+    variant="default"
+    icon={<PlusIcon />}
+    aria-label="新建"
+  />
+</DemoContainer>
+```
+
+### Square
+
+方形变体。
+
+```tsx
+<DemoContainer>
+  <FloatButton
+    shape="square"
+    icon={<PlusIcon />}
+    aria-label="新建"
+  />
+</DemoContainer>
+```
+
+### BackTop
+
+滚动超过 200px 后自动出现回到顶部按钮。
+
+```tsx
+<DemoContainer>
+  <FloatButtonBackTop />
+</DemoContainer>
+```

package/src/components/float-button/stories.tsx

@@ -0,0 +1,68 @@
+/* eslint-disable teamix-evo/no-arbitrary-tw-value, teamix-evo/prefer-gap-over-space -- Storybook demo container needs fixed pixel height + space-y for vertical content listing. */
+import type { Meta, StoryObj } from '@storybook/react';
+import { MessageCircleIcon, PlusIcon } from 'lucide-react';
+import { FloatButton, FloatButtonBackTop } from './index';
+
+const meta: Meta<typeof FloatButton> = {
+  title: '通用 · General/FloatButton 悬浮按钮',
+  component: FloatButton,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const DemoContainer = ({ children }: { children: React.ReactNode }) => (
+  <div className="relative h-[400px] overflow-y-auto rounded-md border border-border">
+    <div className="space-y-4 p-4">
+      {Array.from({ length: 30 }, (_, i) => (
+        <div
+          key={i}
+          className="rounded-md border border-border p-4 text-sm text-muted-foreground"
+        >
+          内容区域 {i + 1}
+        </div>
+      ))}
+    </div>
+    <div className="sticky bottom-4 flex justify-end pr-4">
+      <div className="flex flex-col items-end gap-3">{children}</div>
+    </div>
+  </div>
+);
+
+/** 单个悬浮按钮，滚动时始终固定在右下角。 */
+export const Default: Story = {
+  render: () => (
+    <DemoContainer>
+      <FloatButton icon={<PlusIcon />} aria-label="新建" />
+    </DemoContainer>
+  ),
+};
+
+/** 多个按钮通过 FloatButtonGroup 堆叠。 */
+export const Group: Story = {
+  render: () => (
+    <DemoContainer>
+      <FloatButton icon={<MessageCircleIcon />} aria-label="客服" badge="3" />
+      <FloatButton variant="default" icon={<PlusIcon />} aria-label="新建" />
+    </DemoContainer>
+  ),
+};
+
+/** 方形变体。 */
+export const Square: Story = {
+  render: () => (
+    <DemoContainer>
+      <FloatButton shape="square" icon={<PlusIcon />} aria-label="新建" />
+    </DemoContainer>
+  ),
+};
+
+/** 滚动超过 200px 后自动出现回到顶部按钮。 */
+export const BackTop: Story = {
+  render: () => (
+    <DemoContainer>
+      <FloatButtonBackTop />
+    </DemoContainer>
+  ),
+};

package/src/components/form/index.tsx

@@ -0,0 +1,218 @@
+/**
+ * 表单 Form
+ *
+ * react-hook-form 极薄封装 — 将 RHF FormProvider / Controller 与 Field 系列原子组合，
+ * 实现自动 aria 注入、错误状态联动和无样式重复的表单体验。
+ *
+ * 组合结构：Form > FormField > FormItem > FormLabel + FormControl + FormDescription + FormMessage
+ *
+ * @when
+ * - 表单场景需要 RHF 表单级状态管理
+ * - 需要自动 aria-invalid / aria-describedby 注入
+ * - 需要字段级 error 联动（自动标红 + 错误信息展示）
+ */
+'use client';
+
+import * as React from 'react';
+import { Slot } from 'radix-ui';
+import {
+  Controller,
+  FormProvider,
+  useFormContext,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+} from 'react-hook-form';
+
+import { cn } from '@/lib/utils';
+import { Field, FieldLabel, FieldDescription } from '@/components/field';
+
+// ─── Form ────────────────────────────────────────────────────────────────────
+
+/**
+ * `Form` = `react-hook-form` 的 `FormProvider` 别名。
+ * 配合 `useForm()` 使用，把表单实例下发给所有 `FormField`。
+ */
+const Form = FormProvider;
+
+// ─── FormField context ───────────────────────────────────────────────────────
+
+interface FormFieldContextValue<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+  name: TName;
+}
+
+const FormFieldContext = React.createContext<FormFieldContextValue>(
+  {} as FormFieldContextValue,
+);
+
+/**
+ * `FormField` = `Controller` 包装，把 `name` 注入下层的 useFormField hook。
+ */
+function FormField<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({ ...props }: ControllerProps<TFieldValues, TName>) {
+  return (
+    <FormFieldContext.Provider value={{ name: props.name }}>
+      <Controller {...props} />
+    </FormFieldContext.Provider>
+  );
+}
+
+// ─── FormItem context ────────────────────────────────────────────────────────
+
+interface FormItemContextValue {
+  id: string;
+}
+
+const FormItemContext = React.createContext<FormItemContextValue>(
+  {} as FormItemContextValue,
+);
+
+/**
+ * 组合 FormField + FormItem 的字段元数据，用于 Label / Control / Description / Message。
+ */
+function useFormField() {
+  const fieldContext = React.useContext(FormFieldContext);
+  const itemContext = React.useContext(FormItemContext);
+  const { getFieldState, formState } = useFormContext();
+  const fieldState = getFieldState(fieldContext.name, formState);
+
+  if (!fieldContext) {
+    throw new Error('useFormField should be used within <FormField>');
+  }
+
+  const { id } = itemContext;
+  return {
+    id,
+    name: fieldContext.name,
+    formItemId: `${id}-form-item`,
+    formDescriptionId: `${id}-form-item-description`,
+    formMessageId: `${id}-form-item-message`,
+    ...fieldState,
+  };
+}
+
+// ─── FormItem ────────────────────────────────────────────────────────────────
+
+/**
+ * `FormItem` 渲染单个表单字段容器 — 内部用 `Field` 作为视觉骨架,
+ * 自动从 RHF `fieldState.error` 注入 `data-invalid`。
+ */
+function FormItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof Field>) {
+  const id = React.useId();
+  return (
+    <FormItemContext.Provider value={{ id }}>
+      <FormItemInner className={className} {...props}>
+        {children}
+      </FormItemInner>
+    </FormItemContext.Provider>
+  );
+}
+
+function FormItemInner({
+  children,
+  ...props
+}: React.ComponentProps<typeof Field>) {
+  const { error } = useFormField();
+  return (
+    <Field data-invalid={!!error || undefined} {...props}>
+      {children}
+    </Field>
+  );
+}
+
+// ─── FormLabel ───────────────────────────────────────────────────────────────
+
+/**
+ * `FormLabel` = `FieldLabel` 包装 + 自动 `htmlFor=formItemId`。
+ */
+function FormLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof FieldLabel>) {
+  const { formItemId } = useFormField();
+  return <FieldLabel htmlFor={formItemId} className={className} {...props} />;
+}
+
+// ─── FormControl ─────────────────────────────────────────────────────────────
+
+/**
+ * `FormControl` 用 Radix Slot 注入 `id` / `aria-describedby` / `aria-invalid` 到子控件。
+ * 内部仅放真正的输入控件（Input / Select / Checkbox 等）。
+ */
+function FormControl({ ...props }: React.ComponentProps<typeof Slot.Root>) {
+  const { error, formItemId, formDescriptionId, formMessageId } =
+    useFormField();
+  return (
+    <Slot.Root
+      id={formItemId}
+      aria-describedby={
+        error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId
+      }
+      aria-invalid={!!error}
+      {...props}
+    />
+  );
+}
+
+// ─── FormDescription ─────────────────────────────────────────────────────────
+
+/**
+ * `FormDescription` = `FieldDescription` 包装 + 自动 `id=formDescriptionId`。
+ */
+function FormDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof FieldDescription>) {
+  const { formDescriptionId } = useFormField();
+  return (
+    <FieldDescription id={formDescriptionId} className={className} {...props} />
+  );
+}
+
+// ─── FormMessage ─────────────────────────────────────────────────────────────
+
+/**
+ * `FormMessage` 渲染错误信息 — 有 RHF `error.message` 时取其文本，否则取 children；都没就不渲染。
+ */
+function FormMessage({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<'p'>) {
+  const { error, formMessageId } = useFormField();
+  const body = error ? String(error?.message ?? '') : children;
+
+  if (!body) return null;
+
+  return (
+    <p
+      id={formMessageId}
+      role="alert"
+      data-slot="field-error"
+      className={cn('text-xs font-normal text-destructive -mt-1', className)}
+      {...props}
+    >
+      {body}
+    </p>
+  );
+}
+
+export {
+  useFormField,
+  Form,
+  FormItem,
+  FormField,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+};

package/src/components/form/meta.md

@@ -0,0 +1,16 @@
+# Form
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+表单 Form
+react-hook-form 极薄封装 — 将 RHF FormProvider / Controller 与 Field 系列原子组合，
+实现自动 aria 注入、错误状态联动和无样式重复的表单体验。
+组合结构：Form > FormField > FormItem > FormLabel + FormControl + FormDescription + FormMessage
+
+## 使用场景
+
+- 表单场景需要 RHF 表单级状态管理
+- 需要自动 aria-invalid / aria-describedby 注入
+- 需要字段级 error 联动（自动标红 + 错误信息展示）