import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';

import {TextArea} from '@workday/canvas-kit-react/text-area';

import Alert from './examples/Alert';
import Basic from './examples/Basic';
import Disabled from './examples/Disabled';
import Error from './examples/Error';
import Grow from './examples/Grow';
import LabelPosition from './examples/LabelPosition';
import Placeholder from './examples/Placeholder';
import RefForwarding from './examples/RefForwarding';
import Required from './examples/Required';
import ResizeConstraints from './examples/ResizeConstraints';


# Canvas Kit Text Area

Text Areas allow users to enter and edit multiple lines of text.

[> Workday Design Reference](https://design.workday.com/components/inputs/text-area)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

Text Area should be used in tandem with [Form Field](/components/inputs/form-field/) to meet
accessibility standards.

<ExampleCodeBlock code={Basic} />

### Disabled

Set the `disabled` prop of the Text Area to prevent users from interacting with it.

<ExampleCodeBlock code={Disabled} />

### Placeholder

Set the `placeholder` prop of the Text Input to display a sample of its expected format or value
before a value has been provided.

<ExampleCodeBlock code={Placeholder} />

### Ref Forwarding

Text Area supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
`ref` to its underlying `<textarea>` element.

<ExampleCodeBlock code={RefForwarding} />

### Resize Constraints

Set the `resize` prop of the Text Area to restrict resizing of it to certain dimensions. `resize`
accepts the following values:

- `TextArea.ResizeDirection.Both` (Default)
- `TextArea.ResizeDirection.Horizontal`
- `TextArea.ResizeDirection.None`
- `TextArea.ResizeDirection.Vertical`

<ExampleCodeBlock code={ResizeConstraints} />

### Grow

Set the `grow` prop of the wrapping Form Field to `true` to configure the Text Area to expand to the
width of its container.

<ExampleCodeBlock code={Grow} />

The `grow` prop may also be applied directly to the Text Area if Form Field is not being used.

### Label Position

Set the `labelPosition` prop of the wrapping Form Field to designate the position of the label
relative to the Text Area. `labelPosition` accepts the following values:

- `FormField.LabelPosition.Top` (Default)
- `FormField.LabelPosition.Left`

<ExampleCodeBlock code={LabelPosition} />

### Required

Set the `required` prop of the wrapping Form Field to `true` to indicate that the field is required.
Labels for required fields are suffixed by a red asterisk.

<ExampleCodeBlock code={Required} />

### Error States

Set the `error` prop of the wrapping Form Field to `FormField.ErrorType.Alert` or
`FormField.ErrorType.Error` to set the Text Area to the Alert or Error state, respectively. You will
also need to set the `hintId` and `hintText` props on the Form Field to meet accessibility
standards.

The `error` prop may be applied directly to the Text Area with a value of `TextArea.ErrorType.Alert`
or `TextArea.ErrorType.Error` if Form Field is not being used.

#### Alert

<ExampleCodeBlock code={Alert} />

#### Error

<ExampleCodeBlock code={Error} />

## Component API

<SymbolDoc name="TextArea" fileName="/react/" />

## Specifications

<Specifications file="TextArea.spec.ts" name="Text Area" />