@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,285 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import { useForm } from 'react-hook-form';
+
+import { RadioGroup, RadioGroupItem } from './index';
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/form';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof RadioGroup> = {
+  title: '数据录入 · Data Entry/RadioGroup 单选组',
+  component: RadioGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const FRUITS: Array<{ value: string; label: string; disabled?: boolean }> = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+/** 默认垂直排列，配合外部 `<label htmlFor>` 关联文案。 */
+export const Default: Story = {
+  render: () => (
+    <RadioGroup defaultValue="comfortable">
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="default" id="r1" />
+        <label htmlFor="r1" className="text-xs">
+          默认
+        </label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="comfortable" id="r2" />
+        <label htmlFor="r2" className="text-xs">
+          舒适
+        </label>
+      </div>
+      <div className="flex items-center gap-2">
+        <RadioGroupItem value="compact" id="r3" />
+        <label htmlFor="r3" className="text-xs">
+          紧凑
+        </label>
+      </div>
+    </RadioGroup>
+  ),
+};
+
+/** 水平排列：通过 `orientation="horizontal"` 同时切换键盘方向键导航与视觉布局。 */
+export const Horizontal: Story = {
+  render: () => (
+    <RadioGroup orientation="horizontal" defaultValue="apple">
+      {FRUITS.map((opt) => (
+        <div key={opt.value} className="flex items-center gap-2">
+          <RadioGroupItem value={opt.value} id={`h-${opt.value}`} />
+          <label htmlFor={`h-${opt.value}`} className="text-xs">
+            {opt.label}
+          </label>
+        </div>
+      ))}
+    </RadioGroup>
+  ),
+};
+
+/** 整组禁用 + 单项禁用。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <RadioGroup defaultValue="apple" disabled>
+        {FRUITS.map((opt) => (
+          <div key={opt.value} className="flex items-center gap-2">
+            <RadioGroupItem value={opt.value} id={`gd-${opt.value}`} />
+            <label
+              htmlFor={`gd-${opt.value}`}
+              className="text-xs text-muted-foreground"
+            >
+              {opt.label}
+            </label>
+          </div>
+        ))}
+      </RadioGroup>
+      <RadioGroup defaultValue="apple">
+        {[
+          { value: 'apple', label: '苹果' },
+          { value: 'banana', label: '香蕉', disabled: true },
+          { value: 'orange', label: '橙子' },
+        ].map((opt) => (
+          <div key={opt.value} className="flex items-center gap-2">
+            <RadioGroupItem
+              value={opt.value}
+              id={`id-${opt.value}`}
+              disabled={opt.disabled}
+            />
+            <label
+              htmlFor={`id-${opt.value}`}
+              className={
+                opt.disabled ? 'text-xs text-muted-foreground' : 'text-xs'
+              }
+            >
+              {opt.label}
+            </label>
+          </div>
+        ))}
+      </RadioGroup>
+    </div>
+  ),
+};
+
+/** 受控用法 + `onValueChange` 回调。 */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState('apple');
+    return (
+      <div className="flex flex-col gap-3">
+        <RadioGroup value={value} onValueChange={setValue}>
+          {FRUITS.map((opt) => (
+            <div key={opt.value} className="flex items-center gap-2">
+              <RadioGroupItem value={opt.value} id={`c-${opt.value}`} />
+              <label htmlFor={`c-${opt.value}`} className="text-xs">
+                {opt.label}
+              </label>
+            </div>
+          ))}
+        </RadioGroup>
+        <div className="text-xs text-muted-foreground">
+          已选：{value || '无'}
+        </div>
+      </div>
+    );
+  },
+};
+
+/** 数据驱动写法：业务侧用 `.map` 渲染，无需内置 `dataSource`。 */
+export const WithList: Story = {
+  render: () => (
+    <RadioGroup defaultValue="banana">
+      {FRUITS.map((opt) => (
+        <div key={opt.value} className="flex items-center gap-2">
+          <RadioGroupItem
+            value={opt.value}
+            id={`l-${opt.value}`}
+            disabled={opt.disabled}
+          />
+          <label htmlFor={`l-${opt.value}`} className="text-xs">
+            {opt.label}
+          </label>
+        </div>
+      ))}
+    </RadioGroup>
+  ),
+};
+
+/** 无障碍：用 `aria-labelledby` 关联组级标题文案。 */
+export const WithAriaLabelledby: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <span id="lang-label" className="text-xs">
+        编程语言
+      </span>
+      <RadioGroup
+        orientation="horizontal"
+        aria-labelledby="lang-label"
+        defaultValue="ts"
+      >
+        {[
+          { value: 'ts', label: 'TypeScript' },
+          { value: 'go', label: 'Go' },
+          { value: 'rs', label: 'Rust' },
+        ].map((opt) => (
+          <div key={opt.value} className="flex items-center gap-2">
+            <RadioGroupItem value={opt.value} id={`a-${opt.value}`} />
+            <label htmlFor={`a-${opt.value}`} className="text-xs">
+              {opt.label}
+            </label>
+          </div>
+        ))}
+      </RadioGroup>
+    </div>
+  ),
+};
+
+/** 与 react-hook-form Form 集成：`FormField` 接管 value / onChange / aria。 */
+export const InsideForm: Story = {
+  render: () => {
+    const form = useForm({ defaultValues: { plan: 'pro' } });
+    return (
+      <Form {...form}>
+        <form
+          onSubmit={form.handleSubmit((data) => console.log(data))}
+          className="flex w-72 flex-col gap-4"
+        >
+          <FormField
+            name="plan"
+            rules={{ required: '请选择套餐' }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>套餐</FormLabel>
+                <FormControl>
+                  <RadioGroup
+                    value={field.value}
+                    onValueChange={field.onChange}
+                  >
+                    {[
+                      { value: 'free', label: '免费版' },
+                      { value: 'pro', label: '专业版' },
+                      { value: 'enterprise', label: '企业版' },
+                    ].map((opt) => (
+                      <div key={opt.value} className="flex items-center gap-2">
+                        <RadioGroupItem
+                          value={opt.value}
+                          id={`f-${opt.value}`}
+                        />
+                        <label htmlFor={`f-${opt.value}`} className="text-xs">
+                          {opt.label}
+                        </label>
+                      </div>
+                    ))}
+                  </RadioGroup>
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <Button type="submit">提交</Button>
+        </form>
+      </Form>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function PlanForm() {
+  const form = useForm({ defaultValues: { plan: 'pro' } });
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((data) => console.log(data))}
+        className="flex w-72 flex-col gap-4"
+      >
+        <FormField
+          name="plan"
+          rules={{ required: '请选择套餐' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>套餐</FormLabel>
+              <FormControl>
+                <RadioGroup value={field.value} onValueChange={field.onChange}>
+                  {[
+                    { value: 'free', label: '免费版' },
+                    { value: 'pro', label: '专业版' },
+                    { value: 'enterprise', label: '企业版' },
+                  ].map((opt) => (
+                    <div key={opt.value} className="flex items-center gap-2">
+                      <RadioGroupItem value={opt.value} id={\`f-\${opt.value}\`} />
+                      <label htmlFor={\`f-\${opt.value}\`} className="text-xs">
+                        {opt.label}
+                      </label>
+                    </div>
+                  ))}
+                </RadioGroup>
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">提交</Button>
+      </form>
+    </Form>
+  );
+}`,
+      },
+    },
+  },
+};

package/src/components/rate/index.tsx

@@ -0,0 +1,284 @@
+/**
+ * 评分 Rate
+ *
+ * 通过点击或键盘选择星级，对事物进行快速评级。支持半星、自定义图标、只读与禁用区分。
+ *
+ * @when
+ * - 商品 / 服务评价打分
+ * - 满意度调查
+ * - 内容质量标记或展示
+ */
+'use client';
+
+import * as React from 'react';
+import { Star } from 'lucide-react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+const rateItemVariants = cva(
+  'relative inline-block shrink-0 transition-colors',
+  {
+    variants: {
+      size: {
+        sm: 'size-3.5',
+        default: 'size-4',
+        lg: 'size-5',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+interface RateProps
+  extends Omit<
+      React.ComponentProps<'div'>,
+      'onChange' | 'defaultValue' | 'children'
+    >,
+    VariantProps<typeof rateItemVariants> {
+  /** 当前评分值（受控）。 */
+  value?: number;
+  /** 默认评分值（非受控）。@default 0 */
+  defaultValue?: number;
+  /** 评分总数。@default 5 */
+  count?: number;
+  /** 是否允许半星。@default false */
+  allowHalf?: boolean;
+  /** 是否允许再次点击当前值清零。@default true */
+  allowClear?: boolean;
+  /** 禁用态：不可交互、视觉降透明度。@default false */
+  disabled?: boolean;
+  /** 只读态：不可交互、保持完整视觉。@default false */
+  readOnly?: boolean;
+  /** 尺寸。@default 'default' */
+  size?: 'sm' | 'default' | 'lg';
+  /** 自定义图标节点（替换默认 Star）。 */
+  character?: React.ReactNode;
+  /** 值变化回调（点击或键盘触发）。 */
+  onValueChange?: (value: number) => void;
+  /** 悬停值变化回调（实时；离开时回调 -1）。 */
+  onHoverChange?: (value: number) => void;
+}
+
+function clamp(v: number, min: number, max: number) {
+  return Math.min(Math.max(v, min), max);
+}
+
+function Rate({
+  value: controlledValue,
+  defaultValue = 0,
+  count = 5,
+  allowHalf = false,
+  allowClear = true,
+  disabled = false,
+  readOnly = false,
+  size = 'default',
+  character,
+  onValueChange,
+  onHoverChange,
+  className,
+  'aria-label': ariaLabel = '评分',
+  onMouseLeave,
+  onKeyDown,
+  ...props
+}: RateProps) {
+  const [internalValue, setInternalValue] = React.useState(defaultValue);
+  const [hoverValue, setHoverValue] = React.useState(-1);
+
+  const isControlled = controlledValue !== undefined;
+  const currentValue = isControlled
+    ? (controlledValue as number)
+    : internalValue;
+  const displayValue = hoverValue >= 0 ? hoverValue : currentValue;
+  const interactive = !disabled && !readOnly;
+  const step = allowHalf ? 0.5 : 1;
+
+  const commit = React.useCallback(
+    (next: number) => {
+      const clamped = clamp(next, 0, count);
+      if (!isControlled) setInternalValue(clamped);
+      onValueChange?.(clamped);
+    },
+    [count, isControlled, onValueChange],
+  );
+
+  const updateHover = React.useCallback(
+    (next: number) => {
+      setHoverValue(next);
+      onHoverChange?.(next);
+    },
+    [onHoverChange],
+  );
+
+  const handleClick = (starValue: number) => {
+    if (!interactive) return;
+    const next = allowClear && starValue === currentValue ? 0 : starValue;
+    commit(next);
+  };
+
+  const handleMouseMove = (index: number, e: React.MouseEvent) => {
+    if (!interactive) return;
+    if (allowHalf) {
+      const rect = e.currentTarget.getBoundingClientRect();
+      const isLeft = e.clientX - rect.left < rect.width / 2;
+      updateHover(index + (isLeft ? 0.5 : 1));
+    } else {
+      updateHover(index + 1);
+    }
+  };
+
+  const handleMouseLeave = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (interactive) updateHover(-1);
+    onMouseLeave?.(e);
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(e);
+    if (!interactive) return;
+    let next: number | null = null;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowUp':
+        next = clamp((currentValue || 0) + step, step, count);
+        break;
+      case 'ArrowLeft':
+      case 'ArrowDown':
+        next = clamp((currentValue || 0) - step, 0, count);
+        break;
+      case 'Home':
+        next = step;
+        break;
+      case 'End':
+        next = count;
+        break;
+      case 'Enter':
+      case ' ':
+        // Enter / Space: allowClear 下可清零（值已存在则归零，否则置 1）
+        next = allowClear && currentValue > 0 ? 0 : currentValue || step;
+        break;
+      default:
+        return;
+    }
+    if (next !== null) {
+      e.preventDefault();
+      commit(next);
+    }
+  };
+
+  return (
+    <div
+      data-slot="rate"
+      data-size={size}
+      data-disabled={disabled || undefined}
+      data-readonly={readOnly || undefined}
+      role="radiogroup"
+      aria-label={ariaLabel}
+      aria-disabled={disabled || undefined}
+      aria-readonly={readOnly || undefined}
+      tabIndex={interactive ? 0 : -1}
+      className={cn(
+        'inline-flex items-center gap-0.5 rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        disabled && 'pointer-events-none opacity-50',
+        readOnly && 'pointer-events-none',
+        className,
+      )}
+      onMouseLeave={handleMouseLeave}
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      {Array.from({ length: count }, (_, i) => {
+        const starValue = i + 1;
+        const filled = displayValue >= starValue;
+        const halfFilled =
+          allowHalf && !filled && displayValue >= starValue - 0.5;
+        const state: 'full' | 'half' | 'empty' = filled
+          ? 'full'
+          : halfFilled
+          ? 'half'
+          : 'empty';
+        const ariaLabelItem = allowHalf
+          ? `${starValue} 星(支持半星)`
+          : `${starValue} 星`;
+        const clickValue =
+          allowHalf && halfFilled ? starValue - 0.5 : starValue;
+        const Icon = (
+          <Star
+            className={cn(rateItemVariants({ size }), 'fill-current')}
+            aria-hidden
+          />
+        );
+        return (
+          <button
+            key={i}
+            type="button"
+            role="radio"
+            data-slot="rate-item"
+            data-state={state}
+            data-size={size}
+            aria-checked={currentValue >= starValue}
+            aria-label={ariaLabelItem}
+            tabIndex={-1}
+            disabled={disabled}
+            className={cn(
+              'relative cursor-pointer border-0 bg-transparent p-0 leading-none focus:outline-none',
+              !interactive && 'cursor-default',
+            )}
+            onClick={() => handleClick(clickValue)}
+            onMouseMove={(e) => handleMouseMove(i, e)}
+          >
+            {character ? (
+              <span
+                className={cn(
+                  rateItemVariants({ size }),
+                  'inline-flex items-center justify-center',
+                  state === 'empty' && 'text-border',
+                  state !== 'empty' && 'text-warning',
+                )}
+              >
+                {state === 'half' ? (
+                  <>
+                    <span className="absolute inset-0 inline-flex items-center justify-center text-border">
+                      {character}
+                    </span>
+                    <span
+                      className="absolute inset-0 inline-flex items-center justify-center text-warning"
+                      style={{ clipPath: 'inset(0 50% 0 0)' }}
+                    >
+                      {character}
+                    </span>
+                  </>
+                ) : (
+                  character
+                )}
+              </span>
+            ) : (
+              <span
+                className={cn(
+                  rateItemVariants({ size }),
+                  'inline-block text-border',
+                )}
+              >
+                {Icon}
+                {state !== 'empty' && (
+                  <span
+                    className={cn('absolute inset-0 inline-block text-warning')}
+                    style={
+                      state === 'half'
+                        ? { clipPath: 'inset(0 50% 0 0)' }
+                        : undefined
+                    }
+                  >
+                    {Icon}
+                  </span>
+                )}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export { Rate, rateItemVariants };
+export type { RateProps };

package/src/components/rate/meta.md

@@ -0,0 +1,63 @@
+# Rate
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+评分 Rate
+通过点击或键盘选择星级，对事物进行快速评级。支持半星、自定义图标、只读与禁用区分。
+
+## 使用场景
+
+- 商品 / 服务评价打分
+- 满意度调查
+- 内容质量标记或展示
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `number` | – | – | 当前评分值（受控）。 |
+| `defaultValue` | `number` | – | – | 默认评分值（非受控）。@default 0 |
+| `count` | `number` | – | – | 评分总数。@default 5 |
+| `allowHalf` | `boolean` | – | – | 是否允许半星。@default false |
+| `allowClear` | `boolean` | – | – | 是否允许再次点击当前值清零。@default true |
+| `disabled` | `boolean` | – | – | 禁用态：不可交互、视觉降透明度。@default false |
+| `readOnly` | `boolean` | – | – | 只读态：不可交互、保持完整视觉。@default false |
+| `size` | `'sm' \| 'default' \| 'lg'` | – | – | 尺寸。@default 'default' |
+| `character` | `React.ReactNode` | – | – | 自定义图标节点（替换默认 Star）。 |
+| `onValueChange` | `(value: number) => void` | – | – | 值变化回调（点击或键盘触发）。 |
+| `onHoverChange` | `(value: number) => void` | – | – | 悬停值变化回调（实时；离开时回调 -1）。 |
+
+## 示例
+
+### Sizes
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Rate size="sm" defaultValue={3} />
+  <Rate size="default" defaultValue={3} />
+  <Rate size="lg" defaultValue={3} />
+</div>
+```
+
+### CustomCharacter
+
+```tsx
+<Rate
+  defaultValue={3}
+  character={<Heart className="size-4 fill-current" aria-hidden />}
+/>
+```
+
+### Keyboard
+
+```tsx
+<div className="flex flex-col gap-2">
+  <Rate defaultValue={3} allowHalf />
+  <p className="text-xs text-muted-foreground">
+    Tab 聚焦后按 ←↓ / →↑ 调整，Home / End 跳到最小 / 最大，Enter 或 Space
+    在已有值时清零。
+  </p>
+</div>
+```