# Textarea Component

The `TextareaComponent` provides a styled multi-line text input with support for resizing, length constraints, and full accessibility features.

## Features

- **Resize Control**: Configurable resize behavior (none, both, horizontal, vertical)
- **Length Constraints**: Min/max length validation with visual feedback
- **Accessibility**: Full ARIA support with proper labeling and error announcements
- **Event Handling**: Real-time value change events
- **Styling**: Consistent design token integration with focus states
- **Validation**: Error states and helper text support

## Usage

### Basic Textarea

```html
<ccl-textarea 
  placeholder="Enter your message"
  rows="4">
</ccl-textarea>
```

### With FormFieldWrapper

```html
<ccl-form-field-wrapper 
  label="Message" 
  hint="Maximum 500 characters"
  required>
  <ccl-textarea 
    id="message" 
    rows="4" 
    maxLength="500"
    placeholder="Enter your message"
    (valueChange)="onMessageChange($event)">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### With Length Constraints

```html
<ccl-form-field-wrapper 
  label="Description" 
  hint="Between 10 and 1000 characters">
  <ccl-textarea 
    id="description" 
    rows="6"
    minLength="10"
    maxLength="1000"
    placeholder="Enter description">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### With Resize Control

```html
<ccl-form-field-wrapper label="Comments">
  <ccl-textarea 
    id="comments" 
    rows="3"
    resize="both"
    placeholder="Add your comments">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### With Error State

```html
<ccl-form-field-wrapper 
  label="Feedback" 
  error="Message is too short">
  <ccl-textarea 
    id="feedback" 
    rows="5"
    minLength="50"
    error="true"
    errorMessage="Message is too short">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

## API Reference

### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `placeholder` | `string` | `''` | Placeholder text |
| `disabled` | `boolean` | `false` | Disable the textarea |
| `readonly` | `boolean` | `false` | Make the textarea readonly |
| `error` | `boolean` | `false` | Show error state styling |
| `errorMessage` | `string` | `''` | Error message to display |
| `helperText` | `string` | `''` | Helper text below the textarea |
| `rows` | `number` | `4` | Number of visible text lines |
| `cols` | `number` | `undefined` | Number of visible character columns |
| `maxLength` | `number` | `undefined` | Maximum number of characters |
| `minLength` | `number` | `undefined` | Minimum number of characters |
| `resize` | `'none' \| 'both' \| 'horizontal' \| 'vertical'` | `'vertical'` | Resize behavior |

### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `valueChange` | `EventEmitter<string>` | Emitted when text value changes |

## Component Setup

### TypeScript Component

```typescript
import { Component } from '@angular/core';
import { TextareaComponent } from '@Crystal-Code-Labs/ccl-ui-components';

@Component({
  selector: 'app-example',
  template: `
    <ccl-textarea 
      placeholder="Enter your message"
      rows="4"
      maxLength="500"
      (valueChange)="onValueChange($event)">
    </ccl-textarea>
  `,
  imports: [TextareaComponent]
})
export class ExampleComponent {
  message = '';
  
  onValueChange(value: string): void {
    this.message = value;
    console.log('Message:', value);
  }
}
```

## Styling

### CSS Classes

- `.ccl-textarea-wrapper` - Main wrapper container
- `.ccl-textarea` - Textarea element styling
- `.ccl-textarea__helper` - Helper text styling
- `.ccl-textarea__error` - Error message styling

### Design Tokens Used

- `--color-text` - Text color
- `--color-border` - Border color
- `--color-primary-500` - Focus state color
- `--color-error-500` - Error state color
- `--color-success-500` - Helper text color
- `--color-background-default` - Background color
- `--color-background-surface` - Disabled/readonly background
- `--color-muted` - Placeholder text color
- `--typography-font-family-sans` - Font family
- `--typography-font-size-md` - Font size
- `--spacing-sm` - Padding
- `--spacing-md` - Padding
- `--radius-sm` - Border radius
- `--motion-fast` - Transition timing

### Resize Variants

The component supports different resize behaviors:

- `none` - No resizing allowed
- `both` - Resize both horizontally and vertically
- `horizontal` - Resize only horizontally
- `vertical` - Resize only vertically (default)

## Accessibility Features

### Keyboard Navigation
- **Tab**: Focus the textarea
- **Arrow Keys**: Navigate within text
- **Ctrl/Cmd + A**: Select all text
- **Ctrl/Cmd + Z**: Undo (browser dependent)

### ARIA Support
- `aria-invalid`: Set when in error state
- `aria-describedby`: Links to helper text and error messages
- Proper labeling for screen readers

### Screen Reader Support
- Placeholder text is announced
- Helper text is linked via `aria-describedby`
- Error messages are announced immediately

## Examples

### Form Integration

```typescript
export class FormComponent {
  form = this.fb.group({
    message: ['', [Validators.required, Validators.minLength(10)]],
    description: ['', Validators.maxLength(1000)]
  });
  
  onMessageChange(value: string) {
    this.form.patchValue({ message: value });
  }
  
  onDescriptionChange(value: string) {
    this.form.patchValue({ description: value });
  }
}
```

### Character Counter

```typescript
export class CharacterCounterComponent {
  message = '';
  maxLength = 500;
  
  get remainingChars(): number {
    return this.maxLength - this.message.length;
  }
  
  get isNearLimit(): boolean {
    return this.remainingChars < 50;
  }
  
  get isOverLimit(): boolean {
    return this.remainingChars < 0;
  }
}
```

```html
<ccl-form-field-wrapper 
  label="Message" 
  [hint]="isOverLimit ? 'Character limit exceeded!' : `${remainingChars} characters remaining`"
  [error]="isOverLimit ? 'Message too long' : ''">
  <ccl-textarea 
    id="message" 
    rows="4"
    [maxLength]="maxLength"
    (valueChange)="message = $event">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### Auto-resize Textarea

```typescript
export class AutoResizeComponent {
  message = '';
  
  onValueChange(value: string) {
    this.message = value;
    this.adjustHeight();
  }
  
  adjustHeight() {
    const textarea = document.getElementById('auto-textarea') as HTMLTextAreaElement;
    if (textarea) {
      textarea.style.height = 'auto';
      textarea.style.height = textarea.scrollHeight + 'px';
    }
  }
}
```

```html
<ccl-textarea 
  id="auto-textarea"
  rows="1"
  resize="none"
  placeholder="Type your message..."
  (valueChange)="onValueChange($event)">
</ccl-textarea>
```

### Rich Text Integration

```typescript
export class RichTextComponent {
  content = '';
  
  onContentChange(value: string) {
    this.content = value;
    // Process markdown or other formatting
    this.processContent(value);
  }
  
  processContent(text: string) {
    // Convert markdown to HTML, etc.
  }
}
```

## Best Practices

### Length Constraints
- Set reasonable min/max lengths based on use case
- Provide clear feedback when limits are approached
- Consider showing character count for longer texts

### Resize Behavior
- Use `vertical` resize for most cases (prevents layout issues)
- Use `both` only when horizontal space is available
- Use `none` for fixed-size layouts

### Performance
- Use `OnPush` change detection for large forms
- Debounce value change events if processing is expensive
- Consider virtual scrolling for very long texts

### Accessibility
- Always provide meaningful labels
- Use helper text to explain requirements
- Ensure sufficient color contrast for all states
- Test with screen readers

### Validation
- Provide real-time feedback when possible
- Use both visual and programmatic validation
- Show specific error messages, not just "invalid"

## Migration from HTML Textarea

### Before (HTML)
```html
<textarea 
  id="message" 
  rows="4" 
  cols="50"
  maxlength="500"
  placeholder="Enter your message">
</textarea>
```

### After (Component)
```html
<ccl-textarea 
  id="message" 
  rows="4" 
  cols="50"
  maxLength="500"
  placeholder="Enter your message"
  (valueChange)="onMessageChange($event)">
</ccl-textarea>
```

```typescript
onMessageChange(value: string) {
  // Handle value change
  this.message = value;
}
```

## Common Use Cases

### Contact Forms
```html
<ccl-form-field-wrapper 
  label="Message" 
  hint="Tell us how we can help"
  required>
  <ccl-textarea 
    id="contact-message" 
    rows="5"
    maxLength="1000"
    placeholder="Describe your inquiry...">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### Comments and Reviews
```html
<ccl-form-field-wrapper 
  label="Review" 
  hint="Share your experience"
  required>
  <ccl-textarea 
    id="review" 
    rows="6"
    minLength="50"
    maxLength="2000"
    placeholder="Write your review...">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

### Code/Technical Content
```html
<ccl-form-field-wrapper label="Code Snippet">
  <ccl-textarea 
    id="code" 
    rows="10"
    resize="both"
    placeholder="Paste your code here...">
  </ccl-textarea>
</ccl-form-field-wrapper>
```

## Testing

The component includes comprehensive unit tests covering:
- Value change events
- Length constraints
- Resize behavior
- Accessibility attributes
- Error states
- Disabled and readonly states

Run tests with:
```bash
ng test --include="**/textarea.spec.ts"
```