docs: TextArea tag page rewrite

docs/source/includes/tags/textarea.md

@@ -2,20 +2,19 @@
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| name | <code>string</code> |  | Name of the element |
-| toName | <code>string</code> |  | Name of the element that you want to label |
-| value | <code>string</code> |  | Pre-filled value |
-| [label] | <code>string</code> |  | Label text |
-| [placeholder] | <code>string</code> |  | Placeholder text |
+| name | <code>string</code> |  | Name to identify the TextArea |
+| toName | <code>string</code> |  | Name assigned to the object tag that the TextArea is labeling |
+| [value] | <code>string</code> |  | A pre-filled default value that appears within the rendered TextArea field and can be submitted |
+| [placeholder] | <code>string</code> |  | Placeholder text that appears inside the rendered TextArea field, but unlike `value` it cannot be submitted |
 | [maxSubmissions] | <code>string</code> |  | Maximum number of submissions |
-| [editable] | <code>boolean</code> | <code>false</code> | Whether to display an editable textarea |
-| [skipDuplicates] | <code>boolean</code> | <code>false</code> | Prevent duplicates in textarea inputs |
-| [transcription] | <code>boolean</code> | <code>false</code> | If false, always show editor |
-| [displayMode] | <code>tag</code> \| <code>region-list</code> | <code>tag</code> | Display mode for the textarea; region-list shows it for every region in regions list |
-| [rows] | <code>number</code> |  | Number of rows in the textarea |
-| [required] | <code>boolean</code> | <code>false</code> | Validate whether content in textarea is required |
+| [editable] | <code>boolean</code> | <code>false</code> | Whether to display an icon that allows the annotator to edit their text after adding it |
+| [transcription] | <code>boolean</code> | <code>false</code> | When set to true and used with `editable="true"`, the TextArea UI will remain an editable field even after you add your text |
+| [skipDuplicates] | <code>boolean</code> | <code>false</code> | When set to true, a pop-up warning will appear and prevent duplicate values. See [the example below](#Example-Enforce-unique-values) |
+| [displayMode] | <code>tag</code> \| <code>region-list</code> | <code>tag</code> | Display mode for the TextArea; when set to `region-list` there will be an input field for every region in the Regions panel. See [the example below](#Example-Region-list-TextArea-fields) |
+| [rows] | <code>number</code> | <code>1</code> | Number of rows in the TextArea input field. If `1`, you can submit text by pressing Enter. If greater than `1`, you can submit text by clicking **Add** or pressing Shift + Enter |
+| [required] | <code>boolean</code> | <code>false</code> | Determine whether content in TextArea is required |
 | [requiredMessage] | <code>string</code> |  | Message to show if validation fails |
-| [showSubmitButton] | <code>boolean</code> |  | Whether to show or hide the submit button. By default it shows when there are more than one rows of text, such as in textarea mode. |
+| [showSubmitButton] | <code>boolean</code> |  | Determine whether to show or hide the **Add** button. By default it's hidden if `rows="1"`, and it's visible if there are more than 1 row. |
 | [perRegion] | <code>boolean</code> |  | Use this tag to label regions instead of whole objects |
 | [perItem] | <code>boolean</code> |  | Use this tag to label items inside objects instead of whole objects |
 

docs/source/tags/textarea.md

@@ -12,18 +12,23 @@ Use with the following data types: audio, image, HTML, paragraphs, text, time se
 
 {% insertmd includes/tags/textarea.md %}
 
-### Example
+### Example: Basic TextArea
 
-Basic labeling configuration to display only a text area
+You can open this example in the playground and experiment with different parameters. 
 
 ```html
 <View>
-  <TextArea name="ta"></TextArea>
+  <TextArea name="text-area"></TextArea>
 </View>
 ```
-### Example
 
-You can combine the `TextArea` tag with other tags for OCR or other transcription tasks
+### Example: Region list TextArea fields
+
+This example combines the `TextArea` tag with other tags for OCR labeling. 
+
+Because `displayMode="region-list"`, the text area fields are displayed under the **Regions** panel instead of in the labeling interface. 
+
+![Screenshot](/images/tags/textarea-ocr.png)
 
 ```html
 <View>
@@ -36,13 +41,49 @@ You can combine the `TextArea` tag with other tags for OCR or other transcriptio
   <TextArea name="transcription" toName="image" editable="true" perRegion="true" required="true" maxSubmissions="1" rows="5" placeholder="Recognized Text" displayMode="region-list"/>
 </View>
 ```
-### Example
+### Example: Enforce unique values 
 
-You can keep submissions unique.
+To keep submissions unique, you can set `skipDuplicates="true"`. The user will receive a pop-up message if they attempt to enter the same value twice. 
+
+![Screenshot](/images/tags/textarea-unique.png)
 
 ```html
 <View>
   <Audio name="audio" value="$audio"/>
   <TextArea name="genre" toName="audio" skipDuplicates="true" />
 </View>
 ```
+
+### Example: Ensure users can submit by pressing Enter
+
+If you are trying to optimize your annotation process by speed, you may want to use keyboard shortcuts or want to avoid additional clicks.
+
+For that you should note the following:
+
+- If `rows="1"` you can press Enter to submit your text. 
+- If rows > 1, the **Add** button appears. You can click this or press Shift + Enter. 
+- You do not have to add the text (meaning click **Add** or pressing Enter/Shift + Enter) to save your text when you press **Submit**. 
+
+  It is enough to simply enter your text into the input field. You only need to add your text if you want to include multiple submissions from the same TextArea. See the video below. 
+
+<video style="max-width: 600px;" class="gif-border" autoplay loop muted>
+  <source src="/images/tags/textarea-demo.mp4">
+</video>
+
+
+!!! info Tip
+    You can click Control + Enter (Windows) or Command + Enter (Mac) to submit the annotation. 
+
+    You can also configure your own [custom hotkeys](/guide/user_account#Set-custom-hotkeys) 
+
+```html
+<View>
+  <Header value="Press Enter to submit"/>
+  <Text name="text1" value="Example text 1" />
+  <TextArea name="text-area-1" toName="text1" rows="1" />
+
+  <Header value="Press Shift + Enter to submit"/>
+  <Text name="text2" value="Example text 2" />
+  <TextArea name="text-area-2" toName="text2" rows="3" />
+</View>
+```

web/libs/core/src/lib/utils/schema/tags.json

@@ -2441,31 +2441,25 @@
     "attrs": {
       "name": {
         "name": "name",
-        "description": "Name of the element",
+        "description": "Name to identify the TextArea",
         "type": "string",
         "required": true
       },
       "toName": {
         "name": "toName",
-        "description": "Name of the element that you want to label",
+        "description": "Name assigned to the object tag that the TextArea is labeling",
         "type": "string",
         "required": true
       },
       "value": {
         "name": "value",
-        "description": "Pre-filled value",
-        "type": "string",
-        "required": true
-      },
-      "label": {
-        "name": "label",
-        "description": "Label text",
+        "description": "A pre-filled default value that appears within the rendered TextArea field and can be submitted",
         "type": "string",
         "required": false
       },
       "placeholder": {
         "name": "placeholder",
-        "description": "Placeholder text",
+        "description": "Placeholder text that appears inside the rendered TextArea field, but unlike `value` it cannot be submitted",
         "type": "string",
         "required": false
       },
@@ -2477,41 +2471,42 @@
       },
       "editable": {
         "name": "editable",
-        "description": "Whether to display an editable textarea",
+        "description": "Whether to display an icon that allows the annotator to edit their text after adding it",
         "type": ["true", "false"],
         "required": false,
         "default": false
       },
-      "skipDuplicates": {
-        "name": "skipDuplicates",
-        "description": "Prevent duplicates in textarea inputs",
+      "transcription": {
+        "name": "transcription",
+        "description": "When set to true and used with `editable=\"true\"`, the TextArea UI will remain an editable field even after you add your text",
         "type": ["true", "false"],
         "required": false,
         "default": false
       },
-      "transcription": {
-        "name": "transcription",
-        "description": "If false, always show editor",
+      "skipDuplicates": {
+        "name": "skipDuplicates",
+        "description": "When set to true, a pop-up warning will appear and prevent duplicate values. See [the example below](#Example-Enforce-unique-values)",
         "type": ["true", "false"],
         "required": false,
         "default": false
       },
       "displayMode": {
         "name": "displayMode",
-        "description": "Display mode for the textarea; region-list shows it for every region in regions list",
+        "description": "Display mode for the TextArea; when set to `region-list` there will be an input field for every region in the Regions panel. See [the example below](#Example-Region-list-TextArea-fields)",
         "type": ["tag", "region-list"],
         "required": false,
         "default": "tag"
       },
       "rows": {
         "name": "rows",
-        "description": "Number of rows in the textarea",
+        "description": "Number of rows in the TextArea input field. If `1`, you can submit text by pressing Enter. If greater than `1`, you can submit text by clicking **Add** or pressing Shift + Enter",
         "type": "number",
-        "required": false
+        "required": false,
+        "default": 1
       },
       "required": {
         "name": "required",
-        "description": "Validate whether content in textarea is required",
+        "description": "Determine whether content in TextArea is required",
         "type": ["true", "false"],
         "required": false,
         "default": false
@@ -2524,7 +2519,7 @@
       },
       "showSubmitButton": {
         "name": "showSubmitButton",
-        "description": "Whether to show or hide the submit button. By default it shows when there are more than one rows of text, such as in textarea mode.",
+        "description": "Determine whether to show or hide the **Add** button. By default it's hidden if `rows=\"1\"`, and it's visible if there are more than 1 row.",
         "type": ["true", "false"],
         "required": false
       },

web/libs/editor/src/tags/control/TextArea/TextArea.jsx

@@ -59,20 +59,19 @@ const { TextArea } = Input;
  * @name TextArea
  * @meta_title Textarea Tag for Text areas
  * @meta_description Customize Label Studio with the TextArea tag to support audio transcription, image captioning, and OCR tasks for machine learning and data science projects.
- * @param {string} name                    - Name of the element
- * @param {string} toName                  - Name of the element that you want to label
- * @param {string} value                   - Pre-filled value
- * @param {string=} [label]                - Label text
- * @param {string=} [placeholder]          - Placeholder text
+ * @param {string} name                    - Name to identify the TextArea
+ * @param {string} toName                  - Name assigned to the object tag that the TextArea is labeling
+ * @param {string} [value]                 - A pre-filled default value that appears within the rendered TextArea field and can be submitted
+ * @param {string=} [placeholder]          - Placeholder text that appears inside the rendered TextArea field, but unlike `value` it cannot be submitted
  * @param {string=} [maxSubmissions]       - Maximum number of submissions
- * @param {boolean=} [editable=false]      - Whether to display an editable textarea
- * @param {boolean} [skipDuplicates=false] - Prevent duplicates in textarea inputs
- * @param {boolean=} [transcription=false] - If false, always show editor
- * @param {tag|region-list} [displayMode=tag] - Display mode for the textarea; region-list shows it for every region in regions list
- * @param {number} [rows]                  - Number of rows in the textarea
- * @param {boolean} [required=false]       - Validate whether content in textarea is required
+ * @param {boolean=} [editable=false]      - Whether to display an icon that allows the annotator to edit their text after adding it
+ * @param {boolean=} [transcription=false] - When set to true and used with `editable="true"`, the TextArea UI will remain an editable field even after you add your text
+ * @param {boolean} [skipDuplicates=false] - When set to true, a pop-up warning will appear and prevent duplicate values. See [the example below](#Example-Enforce-unique-values)
+ * @param {tag|region-list} [displayMode=tag] - Display mode for the TextArea; when set to `region-list` there will be an input field for every region in the Regions panel. See [the example below](#Example-Region-list-TextArea-fields)
+ * @param {number} [rows=1]                - Number of rows in the TextArea input field. If `1`, you can submit text by pressing Enter. If greater than `1`, you can submit text by clicking **Add** or pressing Shift + Enter
+ * @param {boolean} [required=false]       - Determine whether content in TextArea is required
  * @param {string} [requiredMessage]       - Message to show if validation fails
- * @param {boolean=} [showSubmitButton]    - Whether to show or hide the submit button. By default it shows when there are more than one rows of text, such as in textarea mode.
+ * @param {boolean=} [showSubmitButton]    - Determine whether to show or hide the **Add** button. By default it's hidden if `rows="1"`, and it's visible if there are more than 1 row.
  * @param {boolean} [perRegion]            - Use this tag to label regions instead of whole objects
  * @param {boolean} [perItem]              - Use this tag to label items inside objects instead of whole objects
  */