[UIK-2230] Add BulkTextarea documentation

website/docs/.vitepress/sidebarConfig.ts

@@ -190,6 +190,11 @@ export const sideBarConfig: SidebarConfig = [
             activeMatch: '/components/breadcrumbs/',
             text: 'Breadcrumbs',
           },
+          {
+            link: '/components/bulk-textarea/bulk-textarea',
+            activeMatch: '/components/bulk-textarea/',
+            text: 'BulkTextarea',
+          },
           {
             link: '/components/button/button',
             activeMatch: '/components/button/',

website/docs/components/bulk-textarea/bulk-textarea-a11y.md

@@ -0,0 +1,54 @@
+---
+title: BulkTextarea
+tabs: Design('bulk-textarea'), A11y('bulk-textarea-a11y'), API('bulk-textarea-api'), Example('bulk-textarea-code'), Changelog('bulk-textarea-changelog')
+---
+
+_**THIS DOCUMENTATION SHOULD BE CHECKED AND UPDATED AFTER THE COMPONENT WILL BE IMPLEMENTED.**_
+
+## What component has
+
+### Roles and attributes
+
+The following list describes roles and attributes that component already has.
+
+Table: Roles and attributes
+
+| Component               | Role / Attribute        | Usage                                                        |
+| ----------------------- | ----------------------- | ------------------------------------------------------------ |
+| `BulkTextarea.InputField` | `textbox`               | Identifies an field that allows the input of free-form text. |
+|                         | `aria-multiline=”true”` | Indicates that a textbox accepts multiple lines of input.    |
+| CHECK if it is about rows | `aria-live="polite"` | Identifies the container element as a live region in the "polite" state, meaning assistive technology users are informed of changes to the region at the next available opportunity. Announces live message:"Keyword {2}", on each keyboard navigation (Up/Down key) within the textbox rows without errors. |
+| `BulkTextarea.Counter` | `aria-label="{n} out of {n}"` | Sets an accessible name for the element. |
+| | `"aria-label={n} out of {n}, limit reached"` | Sets an accessible name for the element. |
+| | `"aria-label={n} out of {n}, limit exceeded"` | Sets an accessible name for the element. |
+| Buttons inside `BulkTextarea.ErrorsNavigation` | `aria-label="Next error"`, `aria-label="Previous error"` | Sets an accessible names for the elements. |
+| CHECK | `aria-live="polite"` | Identifies the container element as a live region in the "polite" state, meaning assistive technology users are informed of changes to the region at the next available opportunity. Announces live message:"Error {n} out of {n}", while navigating between the errors using buttons. |
+| CHECK IF NEEDED `BulkTextarea.ErrorItem` | `aria-hidden="true"` | Hides noninteractive icon from the assistive technologies. |
+
+### Keyboard support
+
+For detailed information about keyboard support for the Input, refer to the [Keyboard control guide](/core-principles/a11y/a11y-keyboard#input_i_textarea).
+
+## Considerations for developers and designers
+
+- Keep it simple - not all browsers correctly expose multiple labels that are linked to the same form element.
+- **CHECK THIS, maybe it works out of the box** Use labels for every input and make the `for=""` and `id=""` values match. IDs must be unique on each page, only one label can be associated to each unique form element. Make required fields obvious by using an indicator – asterisk, description text, etc.
+ - **CHECK THIS** Fields with error validation should have `aria-describedby` to insure that the associated field level error message is read by assistive technology. If the error message has an `id="my-error-message"`, then the input should have `aria-describedby="my-error-message"`.
+
+ ### Error messages
+
+ Set error messages for the tooltips that will be shown for siighted users and read by assistive technologies. You should set:
+
+- Messages for the specific errors in the invalid lines based on your validation rules
+- Message for the whole invalid input
+
+**These messages aren't set by default in the component.**
+
+## Resources
+
+- [A11y style guide](https://a11y-style-guide.com/style-guide/section-forms.html#kssref-forms-text-fields) describes core principles for the accessible inputs and textarea.
+- Find live examples of accessible inputs with different types in [DigitalA11y project](https://www.digitala11y.com/demos/accessibility-of-html-input-types-examples/).
+
+## Other recommendations
+
+For more accessibility recommendations, refer to the the common [Accessibility guide](/core-principles/a11y/a11y).

website/docs/components/bulk-textarea/bulk-textarea-api.md

@@ -0,0 +1,4 @@
+---
+title: BulkTextarea
+tabs: Design('bulk-textarea'), A11y('bulk-textarea-a11y'), API('bulk-textarea-api'), Example('bulk-textarea-code'), Changelog('bulk-textarea-changelog')
+---

website/docs/components/bulk-textarea/bulk-textarea-changelog.md

@@ -0,0 +1,4 @@
+---
+title: BulkTextarea
+tabs: Design('bulk-textarea'), A11y('bulk-textarea-a11y'), API('bulk-textarea-api'), Example('bulk-textarea-code'), Changelog('bulk-textarea-changelog')
+---

website/docs/components/bulk-textarea/bulk-textarea-code.md

@@ -0,0 +1,8 @@
+---
+title: BulkTextarea
+tabs: Design('bulk-textarea'), A11y('bulk-textarea-a11y'), API('bulk-textarea-api'), Example('bulk-textarea-code'), Changelog('bulk-textarea-changelog')
+---
+
+## Expanded BulkTextarea
+
+*HERE, WE SHOULD ADD AN EXAMPLE OF HOW OUR USERS CAN EXPAND THE COMPONENT IF THEY NEED TO CHANGE THE PLACEMENT OF THE CONTROLS.*

website/docs/components/bulk-textarea/bulk-textarea.md

@@ -0,0 +1,131 @@
+---
+title: BulkTextarea
+tabs: Design('bulk-textarea'), A11y('bulk-textarea-a11y'), API('bulk-textarea-api'), Example('bulk-textarea-code'), Changelog('bulk-textarea-changelog')
+---
+
+## Description
+
+**BulkTextarea** is a multiline text field designed for entering lists of comma-separated values.
+
+You can enter a list manually using **Enter** or a comma, or paste a comma-separated list. You can also define your own rules for splitting values into rows.
+
+This component also provides the possibility to validate every row and the whole input.
+
+## Component composition
+
+![](static/bulktextarea-composition.png)
+
+Component consists of the following:
+
+- `BulkTextarea.InputField`
+- `BulkTextarea.Counter`
+- `BulkTextarea.InputField.Row`
+- `BulkTextarea.ErrorItem`
+- `BulkTextarea.ErrorsNavigation`
+- `BulkTextarea.ClearAllButton`
+
+## Appearance
+
+### Sizes
+
+Component has two sizes:
+
+Table: BulkTextarea sizes
+
+| Size (font size) | Appearance example     |
+| ---------------- | ---------------------- |
+| M (`--fs-200`)   | ![](static/bulk-m.png) |
+| L (`--fs-300`)   | ![](static/bulk-l.png) |
+
+### Rows
+
+- Each row is numbered.
+- Rows that fail validation are marked with a `Warning` icon on the right.
+- Rows that exceed the limit are highlighted.
+
+![](static/bulktextarea-rows.png)
+
+## Counter
+
+BulkTextarea includes a counter displaying the number of rows entered. It's always positioned next to the text label.
+
+Table: BulkTextarea with counter
+
+| Size (font size) | Input with label       |
+| ---------------- | ---------------------- |
+| M (`--fs-200`)   | ![](static/bulk-m.png) |
+| L (`--fs-300`)   | ![](static/bulk-l.png) |
+
+### How counter works
+
+1. The counter shows the value limit and updates once user enters at least one character on an empty line.
+2. The counter updates if the user deletes a line.
+3. If the user presses **Enter** or types a comma on **an empty line**, they stay on the same line. This helps avoid adding unnecessary blank lines.
+4. Duplicate lines are counted.
+
+You can set your own validation rules for how invalid values are counted in the counter:
+
+- On new line
+- On blur
+- On submit
+- Immediately on entering at least one character _(we don't recommend this)_
+
+### Values that reached or exceeded limit
+
+When the number of values reaches the limit, the counter changes its theme to `warning`.
+
+![](static/values-limit.png)
+
+Rows with values that exceed the limit are highlighted, and counter changes its theme to `danger`.
+
+![](static/values-off-limit.png)
+
+## Controls
+
+In the component, the controls have a default placement, but if you need to position them elsewhere, you can expand the component and arrange them differently. [Refer to the example](/components/bulk-textarea/bulk-textarea-code#expanded-bulktextarea).
+
+### Clear field button
+
+As soon as at least one character is entered in the field, a button for clearing the field appears next to it. By default, the button is positioned to the bottom right of the field.
+
+![](static/bulktextarea-clear-button.png)
+
+### Navigation buttons
+
+Error navigation shows up after all the values or a single value (depending on the validation method) are validated. The number of errors is shown next to the buttons.
+
+![](static/bulktextarea-error-navigation.png)
+
+CHECK THIS: **When a button is clicked, the cursor moves to the first or last invalid row, depending on the button.** The entire row's value is selected for quick deletion. The text next to the navigation buttons updates to _"Error {n} out of {n}"_ when the cursor is moved using the buttons, keyboard, or mouse.
+
+![](static/bulktextarea-error-navigation-1.png)
+
+When navigating between invalid rows, the text next to the buttons is updated. If you move from an invalid row to a valid row, the counter in the errors navigation buttons stays the same.
+
+### Resize control
+
+You can enable the resize control for the textarea, allowing users to adjust its size. They can stretch it horizontally, vertically, or both ways.
+
+When the textarea can't be stretched further, a scrollbar will appear after a certain number of rows.
+
+::: tip
+Avoid making the textarea smaller than 160–200px in width and 3–4 rows in height. Working with large amounts of data in smaller sizes can be challenging, especially when it serves as a primary input in a form.
+:::
+
+## Interaction
+
+### States
+
+BulkTextarea has the same states and styles as [Textarea](/components/textarea/textarea#interaction).
+
+### Validation
+
+**CHECK THIS** You can define your own validation rules for the input: instant, on submit, onBlur, or on new line. By default, our component uses on new line validation.
+
+### Tooltips
+
+If there are invalid values in the textarea after validation, you can show a tooltip for the entire textarea or for individual rows when the cursor is on them.
+
+![](static/bulktextarea-tooltip.png)
+
+![](static/bulktextarea-tooltip-row.png)

website/docs/components/components-showcase/components-showcase.md

@@ -43,6 +43,12 @@ const group = {
     title: 'Breadcrumbs',
     route: '/intergalactic/components/breadcrumbs/breadcrumbs',
     type: 'components',
+  },
+    bulkTextarea: {
+    title: 'BulkTextarea',
+    route: '/intergalactic/components/bulk-textarea/bulk-textarea',
+    disabled: false,
+    type: 'components',
   },
   button: {
     title: 'Button',

website/docs/components/textarea/textarea-a11y.md

@@ -9,7 +9,7 @@ tabs: Design('textarea'), A11y('textarea-a11y'), API('textarea-api'), Example('t
 
 ### Keyboard support
 
-See detailed information about the keyboard support for the Input in the [Keyboard control guide](/core-principles/a11y/a11y-keyboard#input_i_textarea).
+For detailed information about keyboard support for the Input, refer to the [Keyboard control guide](/core-principles/a11y/a11y-keyboard#input_i_textarea).
 
 ## Considerations for developers
 
@@ -26,4 +26,4 @@ Find live examples in the [A11y style guide](https://a11y-style-guide.com/style-
 
 ## Other recommendations
 
-See more accessibility recommendations in the common [Accessibility guide](/core-principles/a11y/a11y).
+For more accessibility recommendations, refer to the the common [Accessibility guide](/core-principles/a11y/a11y).

website/docs/components/textarea/textarea.md

@@ -101,22 +101,22 @@
 
 ## Description
 
-**Textarea** is a multiline text field designed for capturing a large amount of data, such as comments, descriptions, or lists of links.
+**Textarea** is a multiline text field designed for capturing a large amount of data, such as comments or descriptions.
 
 ## Sizes
 
 Table: Textarea sizes
 
-Size (height in px for one row of text) | Appearance example                 |
-| ------------------------------------- | ---------------------------------- |
-| M (28px)                              | ![](static/m.png) |
-| L (40px)                              | ![](static/l.png) |
+| Size (height in px for one row of text) | Appearance example |
+| --------------------------------------- | ------------------ |
+| M (28px)                                | ![](static/m.png)  |
+| L (40px)                                | ![](static/l.png)  |
 
 ## Resize control
 
 You can enable the resize control for the textarea to allow users to adjust its size. They can stretch it horizontally, vertically, or both ways.
 
-When the textarea cannot be stretched, a scrollbar will appear after a certain number of lines. We recommended adding scrollbars when the textarea has at least 4-5 lines.
+When the textarea cannot be stretched, a scrollbar will appear after a certain number of lines. We recommended adding scrollbars when the textarea has at least 5 lines.
 
 ::: tip
 Avoid making the textarea smaller than 160-200px in width and 3-4 lines in height. Working with large amounts of data in smaller sizes can be challenging, especially when it serves as a primary input in a form.
@@ -130,25 +130,24 @@
 
 Table: Textarea with counter
 
-| Size (height in px for one row of text) | Input with label       | Input without label    |
-| ------------------- | ------------------------------------------ | ---------------------- |
-| M (28px)            | ![](static/counter-M.png) | ![](static/counter-inner-M.png) |
-| L (40px)            | ![](static/counter-L.png) | ![](static/counter-inner-L.png) |
+| Size (height in px for one row of text) | Input with label          |
+| --------------------------------------- | ------------------------- |
+| M (28px)                                | ![](static/counter-M.png) |
+| L (40px)                                | ![](static/counter-L.png) |
 
 ## Interaction
 
 The styles of the textarea in different states correspond to those of the [Input](/components/input/input) component for the same states.
 
 Table: Textarea states
 
-| State   | Normal          | Focus      | Disabled           | Read-only      |
-| ------- | --------------- | ---------- | ------------------ | -------------- |
-| Normal  | ![](static/m.png)         | ![](static/m-focus.png)   | ![](static/m-disabled.png) | ![](static/m-readonly.png) |
-| Valid   | ![](static/m-valid.png)     | ![](static/m-valid-focus.png)       |               |            |
-| Invalid | ![](static/m-invalid.png) | ![](static/m-invalid-focus.png) |              |         |
+| State   | Normal                    | Focus                           | Disabled                   | Read-only                  |
+| ------- | ------------------------- | ------------------------------- | -------------------------- | -------------------------- |
+| Normal  | ![](static/m.png)         | ![](static/m-focus.png)         | ![](static/m-disabled.png) | ![](static/m-readonly.png) |
+| Valid   | ![](static/m-valid.png)   | ![](static/m-valid-focus.png)   |                            |                            |
+| Invalid | ![](static/m-invalid.png) | ![](static/m-invalid-focus.png) |                            |                            |
 
 ## Usage in UX/UI
 
 - Use the Textarea when users need to input a substantial amount of data. For short inputs with 1-3 words, use the [Input](/components/input/input) component instead.
 - Provide a descriptive name for the textarea so that users understand the type of data they should enter.
-