@xsolla/xui-textarea 0.174.3 → 0.176.0

package/README.md

@@ -1,6 +1,68 @@
 # Textarea
 
 A cross-platform React textarea component for multi-line text input. Includes error state and validation message support.
+<!-- BEGIN:xui-mcp-instructions:textarea -->
+A multi-line text input for collecting longer freeform content. Supports five sizes, an optional scroll bar, an optional resize handle, placeholder text, and the full standard input state set. Used wherever the expected input length exceeds a single line — comments, descriptions, messages, notes, and code snippets.
+
+### When to use
+
+When the user needs to enter multiple sentences, paragraphs, or structured freeform content — descriptions, comments, feedback, notes, bios, addresses
+
+When the expected input length is unpredictable or variable and a fixed single-line field would feel too restrictive
+
+In forms where a content field needs to stand visually apart from short text inputs by its height
+
+For developer or admin contexts where code, JSON, or multi-line configuration is entered
+
+### When not to use
+
+- For short, single-value inputs (name, email, URL) — use a standard Input
+- When the user must select from predefined options — use Select or ContextMenu
+- When rich formatting (bold, links, lists) is needed — use a rich-text editor, not TextArea
+- For search queries or single-line filter inputs — use Input with appropriate type
+
+### Content guidelines
+- Labels should be short, specific, and written in sentence case: *"Description"*, *"Additional notes"*, *"Message"*, not *"DESCRIPTION"*.
+- Use labels that clearly describe the expected content: *"Project summary"*, *"Delivery instructions"*, *"Tell us more"*, not vague labels like *"Text"* or *"Write here"*.
+- Helper text should clarify purpose, expected level of detail, or constraints when needed: *"Include key goals and timelines"*, *"Maximum 500 characters"*.
+- Placeholder text should support the label, not replace it. Use short examples or prompts only when they reduce ambiguity, and avoid placing essential instructions in the placeholder because it disappears as the user types.
+- Error messages should be explicit and actionable: *"Enter a description"*, *"Message must be 500 characters or fewer"* — not generic messages like *"Invalid input"*.
+- Keep labels concise. If the field needs more explanation, add helper text nearby — not in the label or placeholder.
+
+Behaviour guidelines (from industry practice)
+
+Auto-grow — for most form contexts, prefer auto-grow behaviour: the field starts at the Size height and expands vertically as the user types, rather than scrolling. Pair this with Resize handle=false and Scroll bar=false. Implement via JavaScript (scrollHeight technique) or a CSS field-sizing: content property.
+
+Fixed height with scroll — for contexts where layout stability matters (e.g. a message composer in a chat UI with a fixed panel), use a fixed height and enable Scroll bar=true so the user can scroll the content within the field.
+
+Character count — if the field has a maximum length, display a character counter below the field (e.g. 240 / 500). Update the counter in real time as the user types. When the limit is reached, prevent further input and switch to State=Error with a descriptive message.
+
+Validation — validate on blur (when the user leaves the field) or on form submit. Do not show errors while the user is actively typing. Switch to State=Error with a specific error message when the value fails validation.
+
+Paste — always allow paste. Do not block Ctrl+V / Cmd+V. If content from paste exceeds the character limit, truncate to the limit and show the character counter at maximum.
+
+Tab key — in most form contexts, Tab should move focus to the next field. In code editors or developer-facing TextAreas where tab indentation is expected, handle Tab to insert a tab character and provide a clear way to exit the field (e.g. Escape followed by Tab, or a documented keyboard shortcut).
+
+Disabled state — the field is not focusable and not editable. If a value is present, it remains visible in muted style. Provide an explanation (tooltip or nearby label) if the reason for disabling is not obvious.
+
+Placeholder disappears — placeholder text is shown only in the empty state. It is not a label and must not be relied upon as the sole description of the field.
+
+### Accessibility
+
+Use a native <textarea> element — it inherits keyboard focus, selection, and browser spellcheck behaviour for free.
+
+Always provide a visible label associated via <label for> or aria-labelledby. Do not use placeholder as the only label — it disappears when the user starts typing and is not reliably announced by all screen readers.
+
+When State=Error, the error message must be linked via aria-describedby so screen readers announce it when the field receives focus.
+
+When State=Disable, the <textarea> element must have the disabled attribute. Disabled fields are not focusable by keyboard.
+
+If a character counter is shown, it must be in an aria-live=*"polite"* region so screen readers announce the count as it updates. Link it to the field via aria-describedby.
+
+If Tab is intercepted to insert indentation (developer use case), provide an accessible escape mechanism and document it: include an aria-description on the field noting how to exit — e.g. *"Press Escape then Tab to move to the next field"*.
+
+The resize handle must be keyboard-operable if implemented. Consider providing ↑ / ↓ arrow key controls to adjust the height when the handle has focus, with aria-label=*"Resize text field"*.
+<!-- END:xui-mcp-instructions:textarea -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-textarea",
-  "version": "0.174.3",
+  "version": "0.176.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,8 +13,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",