@xsolla/xui-field-group 0.189.2 → 0.189.3

package/README.md

@@ -3,11 +3,41 @@
 A cross-platform wrapper that adds a label, required indicator, optional icon, description, and helper text around a form field with consistent vertical spacing.
 
 <!-- BEGIN:xui-mcp-instructions:field-group -->
-This is a pattern component that wraps any form control or content block with a structured set of contextual elements — a label, helper text, and an optional content slot.
-
-Field Group provides a consistent visual and semantic structure around interactive or informational content. It does not prescribe what goes inside — the content area accepts any child component, such as a text input, dropdown, toggle, date picker, or custom control.
-
-Use Field Group whenever a form element or content block needs a label, description, or helper message. It ensures spacing, alignment, and accessibility attributes are applied consistently across different content types.
+A layout wrapper that adds a label, an optional description, and helper text to any form control. FieldGroup is not an input itself — it is the scaffolding that gives a field its visual and semantic identity within a form. Any input component from the design system can be placed in the content slot.
+
+### When to use
+- Whenever a form control needs a visible label, description, or helper text
+- To ensure consistent vertical spacing, label alignment, and text hierarchy across all fields in a form
+- To apply validation messages and error states in a standardised way
+- To wrap non-standard controls (ToggleButtonGroup, ImageUploader, InputRange, Drag&Drop Uploader) in the same form field visual pattern as regular inputs
+
+### When not to use
+- When a field needs no label and no helper text — place the control directly without a FieldGroup wrapper
+- As a layout grid for multi-column form rows — use a separate grid or flex layout to position FieldGroup instances side by side
+- To group multiple related fields under one heading — use a fieldset / legend pattern or a form section component instead
+
+### Content guidelines
+- Label — short, specific, sentence case. Aim for 1–3 words. Examples: *"Email"*, *"Card number"*, *"End date"*, *"Company name"*.
+- Description — one line, informational, no punctuation at end. Example: *"Visible to all team members"*, *"YYYY-MM-DD format"*.
+- Helper text (hint) — factual, concise. One line. Example: *"8–20 characters"*, *"CSV files only"*, *"Enter the 6-digit code from your authenticator app"*.
+- Helper text (error) — specific and actionable. Say what went wrong and what to do: *"Enter a valid email address"* not *"Invalid value"*. *"File must be smaller than 10 MB"* not *"File too large"*.
+- Avoid redundancy — if the label clearly communicates the field's purpose, do not repeat it in the description or helper text.
+
+### Behaviour guidelines
+- Label association — the label must be programmatically linked to the control. For standard inputs use <label for=*"fieldId"*>. For complex controls (ToggleButtonGroup, InputRange, ImageUploader) that are not native <input> elements, use aria-labelledby on the control's container or role=*"group"* with aria-label.
+- Required fields — mark required fields visually (asterisk) and in code (aria-required=*"true"* on the control or required on the input). Always explain the required field convention at the top of the form.
+- Error state — when a field fails validation, the embedded control switches to its State=Error appearance, and the helper text changes to the error message in error colour. Both transitions happen simultaneously. Clear the error when the user begins correcting the value.
+- Description visibility — Description is hidden by default. Enable it only for fields that genuinely need extra context. Avoid enabling Description on every field — it adds visual weight and reduces form scannability.
+- Size consistency — all FieldGroup instances in the same form section must share the same Size. Mixing sizes within a form breaks the visual rhythm and makes labels and helper text appear inconsistent.
+- Read-only fields — for fields that display a value but are not editable, use Label=true and the appropriate read-only control presentation. Do not use State=Disable for read-only display — reserve Disable for temporarily unavailable fields.
+
+### Accessibility
+- The Label must be associated with the control via <label for> (for native inputs) or aria-labelledby / aria-label (for custom controls). Never use Description or Helper text as the only accessible name.
+- For complex controls in the content slot (ToggleButtonGroup, InputRange, ImageUploader, Drag&Drop Uploader), wrap them in a role=*"group"* with aria-labelledby pointing to the FieldGroup's label element.
+- When Helper text shows an error, wrap it in an aria-live=*"polite"* region so screen readers announce the error when it appears without requiring navigation. Also link it via aria-describedby on the control so it is read when the control receives focus.
+- Mark required fields with aria-required=*"true"* on the embedded control, in addition to the visual asterisk on the label.
+- When Description=true, associate the description text with the control via aria-describedby alongside the helper text. Both are supplementary — only the label is mandatory for an accessible name.
+- Ensure colour is not the only way to distinguish the error state — the error message in helper text provides the text-based signal required by WCAG 1.4.1 (Use of Colour).
 <!-- END:xui-mcp-instructions:field-group -->
 
 ## Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-field-group",
-  "version": "0.189.2",
+  "version": "0.189.3",
   "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.189.2",
-    "@xsolla/xui-primitives-core": "0.189.2"
+    "@xsolla/xui-core": "0.189.3",
+    "@xsolla/xui-primitives-core": "0.189.3"
   },
   "peerDependencies": {
     "react": ">=16.8.0",