@delightui/components 0.1.104 → 0.1.106

package/docs/components/atoms/TextArea.md

@@ -0,0 +1,670 @@
+# TextArea
+
+A multi-line text input component that extends the standard HTML textarea with enhanced form integration capabilities. It provides a consistent interface for collecting longer text inputs from users, with full support for controlled and uncontrolled usage patterns, validation, and accessibility features.
+
+## Aliases
+
+- TextArea
+- MultilineInput
+- TextBox
+
+## Props Breakdown
+
+**Extends:** `TextareaHTMLAttributes<HTMLTextAreaElement>` (excluding `value`) + `ControlledFormComponentProps<string>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `initialValue` | `string` | `undefined` | No | The initial value for the field |
+| `checked` | `boolean` | `undefined` | No | The initial value for the field |
+| `value` | `string` | `undefined` | No | The current value of the form field |
+| `onValueChange` | `(value: string) => void` | `undefined` | No | Callback function that is called when the field value changes |
+| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
+| `required` | `boolean` | `false` | No | Whether the form field must have a value |
+| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
+| `id` | `string` | `undefined` | No | Id for the form field |
+| `placeholder` | `string` | `undefined` | No | Placeholder text for the textarea |
+| `rows` | `number` | `undefined` | No | Number of visible text lines for the control |
+| `cols` | `number` | `undefined` | No | Visible width of the text control |
+| `maxLength` | `number` | `undefined` | No | Maximum length of the input value |
+| `minLength` | `number` | `undefined` | No | Minimum length of the input value |
+| `readOnly` | `boolean` | `false` | No | Whether the textarea is read-only |
+| `autoFocus` | `boolean` | `false` | No | Whether the textarea should be focused on mount |
+| `wrap` | `string` | `undefined` | No | How the text in the textarea is to be wrapped when submitted |
+| `resize` | `string` | `undefined` | No | CSS resize property |
+
+Plus all standard HTML textarea attributes (name, form, autoComplete, spellCheck, etc.) except `value`.
+
+## Examples
+
+### Basic TextArea
+
+```tsx
+import { TextArea } from '@delightui/components';
+
+function BasicTextAreaExample() {
+  const [message, setMessage] = useState('');
+
+  return (
+    <div>
+      <p>Character count: {message.length}</p>
+      <TextArea
+        value={message}
+        onValueChange={setMessage}
+        placeholder="Enter your message here..."
+        rows={4}
+      />
+    </div>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, TextArea, Button } from '@delightui/components';
+
+function TextAreaFormExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="description"
+        label="Description"
+        required
+      >
+        <TextArea
+          placeholder="Please provide a detailed description..."
+          rows={6}
+          maxLength={500}
+        />
+      </FormField>
+
+      <FormField
+        name="comments"
+        label="Additional Comments"
+      >
+        <TextArea
+          placeholder="Any additional comments or feedback..."
+          rows={4}
+        />
+      </FormField>
+
+      <Button type="submit">
+        Submit
+      </Button>
+    </Form>
+  );
+}
+```
+
+### TextArea with Character Counter
+
+```tsx
+import { TextArea, Text } from '@delightui/components';
+
+function TextAreaWithCounterExample() {
+  const [content, setContent] = useState('');
+  const maxLength = 200;
+
+  const remainingChars = maxLength - content.length;
+  const isNearLimit = remainingChars <= 20;
+  const isOverLimit = remainingChars < 0;
+
+  return (
+    <div>
+      <TextArea
+        value={content}
+        onValueChange={setContent}
+        placeholder="Write your review..."
+        rows={6}
+        maxLength={maxLength}
+        invalid={isOverLimit}
+      />
+      
+      <div style={{ 
+        display: 'flex', 
+        justifyContent: 'space-between', 
+        alignItems: 'center',
+        marginTop: '8px'
+      }}>
+        <Text 
+          size="small" 
+          color={isOverLimit ? 'error' : isNearLimit ? 'warning' : 'secondary'}
+        >
+          {content.length} / {maxLength} characters
+        </Text>
+        
+        {isOverLimit && (
+          <Text size="small" color="error">
+            {Math.abs(remainingChars)} characters over limit
+          </Text>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Resizable TextArea
+
+```tsx
+import { TextArea } from '@delightui/components';
+
+function ResizableTextAreaExample() {
+  const [content, setContent] = useState('');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Resizable (Default)
+        </Text>
+        <TextArea
+          value={content}
+          onValueChange={setContent}
+          placeholder="This textarea can be resized..."
+          rows={4}
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Vertical Resize Only
+        </Text>
+        <TextArea
+          value={content}
+          onValueChange={setContent}
+          placeholder="This textarea can only be resized vertically..."
+          rows={4}
+          style={{ resize: 'vertical' }}
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          No Resize
+        </Text>
+        <TextArea
+          value={content}
+          onValueChange={setContent}
+          placeholder="This textarea cannot be resized..."
+          rows={4}
+          style={{ resize: 'none' }}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Auto-growing TextArea
+
+```tsx
+import { TextArea } from '@delightui/components';
+
+function AutoGrowingTextAreaExample() {
+  const [content, setContent] = useState('');
+
+  // Calculate rows based on content
+  const calculateRows = (text: string) => {
+    const lines = text.split('\n').length;
+    const minRows = 3;
+    const maxRows = 10;
+    return Math.min(Math.max(lines, minRows), maxRows);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '8px' }}>
+        Auto-growing TextArea
+      </Text>
+      <Text size="small" color="secondary" style={{ marginBottom: '12px' }}>
+        This textarea grows as you type (min 3 rows, max 10 rows)
+      </Text>
+      
+      <TextArea
+        value={content}
+        onValueChange={setContent}
+        placeholder="Start typing and watch the textarea grow..."
+        rows={calculateRows(content)}
+        style={{ resize: 'none' }}
+      />
+    </div>
+  );
+}
+```
+
+### Comment System Example
+
+```tsx
+import { TextArea, Button, Text } from '@delightui/components';
+
+function CommentSystemExample() {
+  const [comment, setComment] = useState('');
+  const [comments, setComments] = useState([
+    { id: 1, author: 'John Doe', content: 'Great article! Very informative.', time: '2 hours ago' },
+    { id: 2, author: 'Jane Smith', content: 'I learned a lot from this. Thank you for sharing.', time: '1 hour ago' }
+  ]);
+
+  const handleSubmit = () => {
+    if (comment.trim()) {
+      const newComment = {
+        id: comments.length + 1,
+        author: 'You',
+        content: comment,
+        time: 'Just now'
+      };
+      setComments([...comments, newComment]);
+      setComment('');
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: '600px' }}>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Comments ({comments.length})
+      </Text>
+      
+      {/* Existing Comments */}
+      <div style={{ marginBottom: '24px' }}>
+        {comments.map((c) => (
+          <div key={c.id} style={{ 
+            border: '1px solid #eee', 
+            borderRadius: '8px', 
+            padding: '16px',
+            marginBottom: '12px'
+          }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '8px' }}>
+              <Text weight="bold">{c.author}</Text>
+              <Text size="small" color="secondary">{c.time}</Text>
+            </div>
+            <Text>{c.content}</Text>
+          </div>
+        ))}
+      </div>
+
+      {/* Add Comment */}
+      <div style={{ 
+        border: '1px solid #ccc', 
+        borderRadius: '8px', 
+        padding: '16px',
+        backgroundColor: '#f9f9fa'
+      }}>
+        <Text weight="bold" style={{ marginBottom: '12px' }}>
+          Add a comment
+        </Text>
+        
+        <TextArea
+          value={comment}
+          onValueChange={setComment}
+          placeholder="What are your thoughts?"
+          rows={4}
+          style={{ marginBottom: '12px' }}
+        />
+        
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <Text size="small" color="secondary">
+            {comment.length} characters
+          </Text>
+          <Button 
+            onClick={handleSubmit}
+            disabled={!comment.trim()}
+            size="Small"
+          >
+            Post Comment
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Feedback Form
+
+```tsx
+import { Form, FormField, TextArea, Button, RadioButton, Text } from '@delightui/components';
+
+function FeedbackFormExample() {
+  const [formData, setFormData] = useState({
+    rating: '',
+    feedback: '',
+    suggestions: ''
+  });
+
+  const handleSubmit = (data: any) => {
+    console.log('Feedback submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <Text weight="bold" size="large" style={{ marginBottom: '20px' }}>
+        We'd love your feedback!
+      </Text>
+
+      <FormField
+        name="rating"
+        label="How would you rate your experience?"
+        required
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton name="rating" value="excellent">Excellent</RadioButton>
+          <RadioButton name="rating" value="good">Good</RadioButton>
+          <RadioButton name="rating" value="average">Average</RadioButton>
+          <RadioButton name="rating" value="poor">Poor</RadioButton>
+        </div>
+      </FormField>
+
+      <FormField
+        name="feedback"
+        label="Tell us about your experience"
+        required
+      >
+        <TextArea
+          placeholder="Please share your thoughts about our service..."
+          rows={5}
+          maxLength={1000}
+        />
+      </FormField>
+
+      <FormField
+        name="suggestions"
+        label="Any suggestions for improvement?"
+      >
+        <TextArea
+          placeholder="How can we make your experience better?"
+          rows={4}
+          maxLength={500}
+        />
+      </FormField>
+
+      <Button type="submit">
+        Submit Feedback
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Code Input TextArea
+
+```tsx
+import { TextArea, Button, Text } from '@delightui/components';
+
+function CodeInputExample() {
+  const [code, setCode] = useState(`function greet(name) {
+  return \`Hello, \${name}!\`;
+}
+
+console.log(greet('World'));`);
+
+  const lineCount = code.split('\n').length;
+
+  return (
+    <div style={{ maxWidth: '600px' }}>
+      <Text weight="bold" style={{ marginBottom: '8px' }}>
+        Code Editor
+      </Text>
+      
+      <div style={{ position: 'relative' }}>
+        <TextArea
+          value={code}
+          onValueChange={setCode}
+          rows={12}
+          style={{ 
+            fontFamily: 'monospace',
+            fontSize: '14px',
+            resize: 'none',
+            paddingLeft: '50px'
+          }}
+        />
+        
+        {/* Line numbers */}
+        <div style={{
+          position: 'absolute',
+          left: '8px',
+          top: '8px',
+          fontFamily: 'monospace',
+          fontSize: '14px',
+          color: '#666',
+          lineHeight: '1.5',
+          pointerEvents: 'none'
+        }}>
+          {Array.from({ length: lineCount }, (_, i) => (
+            <div key={i}>{i + 1}</div>
+          ))}
+        </div>
+      </div>
+      
+      <div style={{ 
+        display: 'flex', 
+        justifyContent: 'space-between', 
+        alignItems: 'center',
+        marginTop: '8px'
+      }}>
+        <Text size="small" color="secondary">
+          Lines: {lineCount} | Characters: {code.length}
+        </Text>
+        
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Button size="Small" type="Outlined" onClick={() => setCode('')}>
+            Clear
+          </Button>
+          <Button size="Small" onClick={() => console.log('Code executed:', code)}>
+            Run
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Disabled and Read-only States
+
+```tsx
+import { TextArea, Text } from '@delightui/components';
+
+function DisabledReadOnlyExample() {
+  const sampleText = "This is some sample content that demonstrates different states of the TextArea component.";
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px' }}>
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Normal TextArea
+        </Text>
+        <TextArea
+          value={sampleText}
+          placeholder="Type here..."
+          rows={3}
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Disabled TextArea
+        </Text>
+        <TextArea
+          value={sampleText}
+          disabled
+          rows={3}
+        />
+      </div>
+
+      <div>
+        <Text weight="bold" style={{ marginBottom: '8px' }}>
+          Read-only TextArea
+        </Text>
+        <TextArea
+          value={sampleText}
+          readOnly
+          rows={3}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Template System
+
+```tsx
+import { TextArea, Button, Text } from '@delightui/components';
+
+function TemplateSystemExample() {
+  const [message, setMessage] = useState('');
+  
+  const templates = [
+    {
+      name: 'Thank You',
+      content: 'Thank you for your interest in our services. We appreciate your business and look forward to working with you.'
+    },
+    {
+      name: 'Follow Up',
+      content: 'I wanted to follow up on our previous conversation. Please let me know if you have any questions or if there\'s anything else I can help you with.'
+    },
+    {
+      name: 'Apology',
+      content: 'I apologize for any inconvenience this may have caused. We are working to resolve the issue and will keep you updated on our progress.'
+    }
+  ];
+
+  const useTemplate = (template: string) => {
+    setMessage(template);
+  };
+
+  return (
+    <div style={{ maxWidth: '600px' }}>
+      <Text weight="bold" style={{ marginBottom: '12px' }}>
+        Message Templates
+      </Text>
+      
+      <div style={{ display: 'flex', gap: '8px', marginBottom: '16px', flexWrap: 'wrap' }}>
+        {templates.map((template, index) => (
+          <Button
+            key={index}
+            size="Small"
+            type="Outlined"
+            onClick={() => useTemplate(template.content)}
+          >
+            {template.name}
+          </Button>
+        ))}
+      </div>
+
+      <TextArea
+        value={message}
+        onValueChange={setMessage}
+        placeholder="Type your message or select a template above..."
+        rows={6}
+      />
+      
+      <div style={{ 
+        display: 'flex', 
+        justifyContent: 'space-between', 
+        alignItems: 'center',
+        marginTop: '12px'
+      }}>
+        <Text size="small" color="secondary">
+          {message.length} characters
+        </Text>
+        
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Button 
+            size="Small" 
+            type="Outlined"
+            onClick={() => setMessage('')}
+            disabled={!message}
+          >
+            Clear
+          </Button>
+          <Button 
+            size="Small"
+            disabled={!message.trim()}
+          >
+            Send
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Validation Example
+
+```tsx
+import { Form, FormField, TextArea, Button, Text } from '@delightui/components';
+
+function ValidationExample() {
+  const [content, setContent] = useState('');
+  const [error, setError] = useState('');
+
+  const minLength = 50;
+  const maxLength = 500;
+
+  const validateContent = (value: string) => {
+    if (value.length < minLength) {
+      setError(`Content must be at least ${minLength} characters long`);
+      return false;
+    }
+    if (value.length > maxLength) {
+      setError(`Content must not exceed ${maxLength} characters`);
+      return false;
+    }
+    setError('');
+    return true;
+  };
+
+  const handleSubmit = (data: any) => {
+    if (validateContent(content)) {
+      console.log('Valid submission:', data);
+    }
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="content"
+        label="Content"
+        required
+        invalid={!!error}
+        message={error}
+      >
+        <TextArea
+          value={content}
+          onValueChange={(value) => {
+            setContent(value);
+            validateContent(value);
+          }}
+          placeholder={`Write your content here (${minLength}-${maxLength} characters)...`}
+          rows={6}
+          invalid={!!error}
+        />
+      </FormField>
+      
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginTop: '8px' }}>
+        <Text 
+          size="small" 
+          color={error ? 'error' : content.length < minLength ? 'warning' : 'success'}
+        >
+          {content.length} / {maxLength} characters
+          {content.length < minLength && ` (${minLength - content.length} more needed)`}
+        </Text>
+      </div>
+
+      <Button 
+        type="submit" 
+        disabled={!!error || content.length < minLength}
+        style={{ marginTop: '16px' }}
+      >
+        Submit
+      </Button>
+    </Form>
+  );
+}
+```