import * as React from "react";
import type { Props } from "./types";
/**
* @orbit-doc-start
* README
* ----------
* # Textarea
*
* To implement Textarea component into your project you'll need to add the import:
*
* ```jsx
* import Textarea from "@kiwicom/orbit-components/lib/Textarea";
* ```
*
* After adding import into your project you can use it simply like:
*
* ```jsx
*
* ```
*
* ## Props
*
* Table below contains all types of the props available in Textarea component.
*
* | Name | Type | Default | Description |
* | :------------- | :------------------------- | :----------- | :----------------------------------------------------------------------------------- |
* | dataAttrs | `Object` | | Optional prop for passing `data-*` attributes to the `textarea` DOM element. |
* | dataTest | `string` | | Optional prop for testing purposes. |
* | id | `string` | | Sets the `id` for the `Textarea`. |
* | defaultValue | `string` | | Specifies the default value of the Textarea. To be used with uncontrolled usage. |
* | disabled | `boolean` | | If `true`, the Textarea will be disabled. |
* | error | `React.Node` | | The error to display beneath the Textarea. [See Functional specs](#functional-specs) |
* | fullHeight | `boolean` | `false` | If `true`, the Textarea will take 100% of parent's height. |
* | help | `React.Node` | | The help to display beneath the Textarea. |
* | label | `Translation` | | The label for the Textarea. |
* | maxLength | `number` | | Specifies the maximum number of characters allowed. |
* | name | `string` | | The name for the Textarea. |
* | onChange | `event => void \| Promise` | | Function for handling onChange event. |
* | onFocus | `event => void \| Promise` | | Function for handling onFocus event. |
* | onBlur | `event => void \| Promise` | | Function for handling onBlur event. |
* | placeholder | `TranslationString` | | The placeholder text for the Textarea. |
* | ref | `func` | | Prop for forwarded ref of the Textarea. [See Functional specs](#functional-specs) |
* | resize | [`enum`](#enum) | `"vertical"` | The resize option for Textarea. |
* | rows | `number` | | Specifies the height of the text area (in lines). |
* | readOnly | `boolean` | | Adds the readOnly attribute to the HTML textarea element. |
* | required | `boolean` | | If `true`, the label is displayed as required. |
* | spaceAfter | [`enum`](#enum) | | Additional `margin-bottom` after component. |
* | tabIndex | `string \| number` | | Specifies the tab order of an element. |
* | value | `string` | | Specifies the value of the Textarea. To be used with controlled usage. |
* | ariaLabel | `string` | | Optional prop to set the `aria-label` attribute value. |
* | ariaLabelledby | `string` | | Optional prop to set the `aria-labelledby` attribute value. |
*
* ### enum
*
* | resize | spaceAfter |
* | :----------- | :----------- |
* | `"vertical"` | `"none"` |
* | `"none"` | `"smallest"` |
* | | `"small"` |
* | | `"normal"` |
* | | `"medium"` |
* | | `"large"` |
* | | `"largest"` |
*
* ## Functional specs
*
* - The `error` prop overwrites the `help` prop, due to higher priority.
*
* - `ref` can be used for example auto-focus the elements immediately after render.
*
*
* Accessibility
* -------------
* ## Accessibility
*
* The Textarea component has been designed with accessibility in mind.
*
* It includes the following properties that provide additional information to screen readers:
*
* | Name | Type | Description |
* | :------------- | :------- | :--------------------------------------------------------------------- |
* | ariaLabel | `string` | Allows you to specify an `aria-label` attribute of the component. |
* | ariaLabelledby | `string` | Allows you to specify an `aria-labelledby` attribute of the component. |
*
* These attributes help users better understand the component's purpose and context when using assistive technologies. However, it's important to follow best practices when using them:
*
* 1. **Always prefer visible labels** - Use the `label` prop whenever possible as visible labels benefit all users.
* 2. Use `ariaLabel` **only** when a visible label cannot be provided.
* 3. Use `ariaLabelledby` to associate the textarea with an existing visible label elsewhere in the DOM.
*
* The `ariaLabelledby` prop works by referencing the `id` attribute of one or more other elements:
*
* 1. Assign a unique `id` to the element that serves as the label
* 2. Pass that `id` value to the `ariaLabelledby` prop of the Textarea component
* 3. For multiple labels, provide space-separated ids (e.g., `"id1 id2 id3"`)
*
* When a screen reader encounters the Textarea, it will use the content of the referenced element(s) as the label, reading them in the order specified.
*
* Note that if both `ariaLabel` and `ariaLabelledby` props are provided, `ariaLabelledby` takes precedence.
*
* ### Examples
*
* The following code snippets show different ways to provide accessible labels:
*
* ```jsx
* // PREFERRED: Using the built-in label prop
*
* ```
*
* Screen reader would announce: "Feedback"
*
* ```jsx
* // Use ariaLabel ONLY when a visible label cannot be provided
*
* ```
*
* Screen reader would announce: "Feedback form for customer comments"
*
* ```jsx
* // Use ariaLabelledby to reference an existing visible label elsewhere in the DOM
*
*
* ```
*
* Screen reader would announce: "Flight #KI2807 Passenger Feedback"
*
* ```jsx
* // Using both ariaLabelledby and ariaLabel (ariaLabelledby takes precedence)
*
*
Customer Feedback
*
*
* ```
*
* Screen reader would announce: "Customer Feedback" (ignoring the ariaLabel)
*
* ### Help and Error Messages
*
* When using the `help` or `error` props, their content is automatically set as `aria-describedby` on the element.
*
* Screen readers will announce this additional information after reading the component's label.
*
* ```jsx
*
* ```
*
* Screen reader would announce: "Feedback. This field is required."
*
* ### Detached Label
*
* For special cases you can use your own, detached `label`. This approach can be useful when you need more control over the label's styling or position:
*
* ```jsx
*
*
* ```
*
* Screen reader would announce: "Your feedback"
*
* This method maintains the necessary association between the label and the textarea element for screen readers.
*
* ### Best Practices
*
* 1. Always use a visible label when possible. The `label` prop is preferred over `ariaLabel`.
*
* 2. Only use `ariaLabel` when a visible label is absolutely not possible in your user interface.
*
* 3. Use `ariaLabelledby` to associate the textarea with existing visible labels that appear elsewhere in the interface.
*
* 4. Use clear, descriptive labels that explain what information is expected in the textarea.
*
* 5. Ensure that error messages are specific and helpful, guiding users on how to correct their input.
*
* 6. Consider that users with screen readers will interact with your textareas differently than sighted users. Test your forms with assistive technologies to ensure a smooth experience.
*
*
* @orbit-doc-end
*/
declare const Textarea: (props: Props) => React.JSX.Element;
export default Textarea;
//# sourceMappingURL=index.d.ts.map