@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/textarea/index.tsx

@@ -0,0 +1,62 @@
+/**
+ * 多行输入框 Textarea
+ *
+ * 用于输入多行文本，如备注、描述、评论等长文本场景。
+ *
+ * @when
+ * - 需要用户输入多行文本时（备注、描述、JSON 等）
+ * - 需要自动撑开高度（原生 `field-sizing-content`）时
+ * - 需要配合字符计数 / 前后缀插槽等复合形态时，请改用 [InputGroup](../input-group/index.tsx) + InputGroupTextarea
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+// ─── Textarea cva ────────────────────────────────────────────────────────────
+
+const textareaVariants = cva(
+  'flex w-full cursor-text rounded-md border border-input bg-transparent font-normal field-sizing-content transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20',
+  {
+    variants: {
+      size: {
+        sm: 'min-h-12 px-2 py-1.5 text-xs',
+        default: 'min-h-16 px-2.5 py-2 text-xs',
+        lg: 'min-h-20 px-3 py-2.5 text-sm',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+    },
+  },
+);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type TextareaSize = 'sm' | 'default' | 'lg';
+
+export interface TextareaProps
+  extends Omit<React.ComponentProps<'textarea'>, 'size'>,
+    VariantProps<typeof textareaVariants> {
+  /** 尺寸。 @default default */
+  size?: TextareaSize;
+}
+
+// ─── Textarea ───────────────────────────────────────────────────────────────
+
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, size, ...props }, ref) => {
+    return (
+      <textarea
+        ref={ref}
+        data-slot="textarea"
+        className={cn(textareaVariants({ size, className }))}
+        {...props}
+      />
+    );
+  },
+);
+Textarea.displayName = 'Textarea';
+
+export { Textarea, textareaVariants };

package/src/components/textarea/meta.md

@@ -0,0 +1,77 @@
+# Textarea
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+多行输入框 Textarea
+用于输入多行文本，如备注、描述、评论等长文本场景。
+
+## 使用场景
+
+- 需要用户输入多行文本时（备注、描述、JSON 等）
+- 需要自动撑开高度（原生 `field-sizing-content`）时
+- 需要配合字符计数 / 前后缀插槽等复合形态时，请改用 [InputGroup](../input-group/index.tsx) + InputGroupTextarea
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `TextareaSize` | `default` | – | 尺寸。 |
+
+## 示例
+
+### Sizes
+
+可以通过设置 `size` 属性控制多行输入框的尺寸。
+
+```tsx
+<div className="flex flex-col gap-3 w-80">
+  <Textarea size="sm" placeholder="小 Small" />
+  <Textarea placeholder="中 Default" />
+  <Textarea size="lg" placeholder="大 Large" />
+</div>
+```
+
+### Invalid
+
+通过 `aria-invalid` 标记错误状态，用于表单校验失败时。
+
+```tsx
+<Textarea
+  placeholder="此字段为必填项"
+  aria-invalid="true"
+  className="w-80"
+/>
+```
+
+### ReadOnly
+
+`readOnly` 属性让多行输入框只读。
+
+```tsx
+<Textarea
+  readOnly
+  value="只读内容，用户可复制但无法编辑"
+  className="w-80"
+/>
+```
+
+### WithRows
+
+Textarea 默认使用 `field-sizing-content` 自动撑开高度，也可以通过 `rows` 固定行数。
+
+```tsx
+<div className="flex flex-col gap-3 w-80">
+  <Textarea
+    rows={3}
+    placeholder="固定 3 行"
+    className="field-sizing-fixed"
+  />
+  <Textarea
+    rows={6}
+    placeholder="固定 6 行"
+    className="field-sizing-fixed"
+  />
+</div>
+```

package/src/components/textarea/stories.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Textarea } from './index';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupTextarea,
+  InputGroupShowCount,
+} from '@/components/input-group';
+
+const meta: Meta<typeof Textarea> = {
+  title: '数据录入 · Data Entry/Textarea 多行输入',
+  component: Textarea,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '原生 `<textarea>` 包装：size 三档字号与 Input 对齐，高度自适应由 CSS `field-sizing-content` 原生提供（无 minRows/maxRows props）。需要字符计数 / 前后缀插槽请使用 [InputGroup](/docs/数据录入-·-data-entry-inputgroup-输入框组合--docs) + InputGroupTextarea。',
+      },
+      source: { type: 'dynamic' },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { placeholder: '请输入备注信息...' },
+};
+
+/** 可以通过设置 `size` 属性控制多行输入框的尺寸。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3 w-80">
+      <Textarea size="sm" placeholder="小 Small" />
+      <Textarea placeholder="中 Default" />
+      <Textarea size="lg" placeholder="大 Large" />
+    </div>
+  ),
+};
+
+/** 添加 `disabled` 属性即可让多行输入框处于不可用状态。 */
+export const Disabled: Story = {
+  render: () => <Textarea placeholder="不可编辑" disabled className="w-80" />,
+};
+
+/** 通过 `aria-invalid` 标记错误状态，用于表单校验失败时。 */
+export const Invalid: Story = {
+  render: () => (
+    <Textarea
+      placeholder="此字段为必填项"
+      aria-invalid="true"
+      className="w-80"
+    />
+  ),
+};
+
+/** `readOnly` 属性让多行输入框只读。 */
+export const ReadOnly: Story = {
+  render: () => (
+    <Textarea
+      readOnly
+      value="只读内容，用户可复制但无法编辑"
+      className="w-80"
+    />
+  ),
+};
+
+/** Textarea 默认使用 `field-sizing-content` 自动撑开高度，也可以通过 `rows` 固定行数。 */
+export const WithRows: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3 w-80">
+      <Textarea
+        rows={3}
+        placeholder="固定 3 行"
+        className="field-sizing-fixed"
+      />
+      <Textarea
+        rows={6}
+        placeholder="固定 6 行"
+        className="field-sizing-fixed"
+      />
+    </div>
+  ),
+};
+
+/**
+ * 配合 InputGroup + InputGroupShowCount 在右下角展示字符计数；
+ * 越界时计数索引会自动变为 destructive 色。
+ */
+export const WithShowCount: Story = {
+  render: function WithShowCountStory() {
+    const [value, setValue] = useState('');
+    const max = 100;
+    return (
+      <InputGroup className="w-80">
+        <InputGroupTextarea
+          placeholder="请输入备注信息..."
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          rows={4}
+          className="field-sizing-fixed"
+        />
+        <InputGroupAddon align="block-end" className="justify-end">
+          <InputGroupShowCount current={value.length} max={max} />
+        </InputGroupAddon>
+      </InputGroup>
+    );
+  },
+};