@xsolla/xui-field-group 0.148.0 → 0.148.1

package/README.md

@@ -0,0 +1,197 @@
+# Field Group
+
+A cross-platform React wrapper component that adds consistent labeling, required indicators, helper text, and spacing to form fields.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-field-group
+# or
+yarn add @xsolla/xui-field-group
+```
+
+## Demo
+
+### Basic Field Group
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+
+export default function BasicFieldGroup() {
+  return (
+    <FieldGroup label="Username">
+      <Input placeholder="Enter username" />
+    </FieldGroup>
+  );
+}
+```
+
+### Required Field
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+
+export default function RequiredField() {
+  return (
+    <FieldGroup label="Email" required>
+      <Input type="email" placeholder="Enter email" />
+    </FieldGroup>
+  );
+}
+```
+
+### With Helper Text
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+
+export default function HelperField() {
+  return (
+    <FieldGroup
+      label="Password"
+      helper="Must be at least 8 characters"
+    >
+      <Input type="password" placeholder="Enter password" />
+    </FieldGroup>
+  );
+}
+```
+
+### With Icon
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+import { Info } from '@xsolla/xui-icons-base';
+
+export default function IconField() {
+  return (
+    <FieldGroup
+      label="API Key"
+      icon={<Info />}
+    >
+      <Input placeholder="Enter API key" />
+    </FieldGroup>
+  );
+}
+```
+
+## Anatomy
+
+```jsx
+import { FieldGroup } from '@xsolla/xui-field-group';
+
+<FieldGroup
+  label="Field Label"          // Label text
+  required={false}             // Show required asterisk
+  helper="Helper text"         // Helper text below field
+  icon={<Icon />}              // Icon next to label
+  size="md"                    // Size variant
+  marginBottom={16}            // Bottom margin (spacing)
+  htmlFor="field-id"           // Associate with form field
+>
+  <FormField />                // Form control component
+</FieldGroup>
+```
+
+## Examples
+
+### Form with Field Groups
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+import { Select } from '@xsolla/xui-select';
+import { Textarea } from '@xsolla/xui-textarea';
+import { Button } from '@xsolla/xui-button';
+
+export default function CompleteForm() {
+  return (
+    <div style={{ maxWidth: 400 }}>
+      <FieldGroup label="Full Name" required>
+        <Input placeholder="John Doe" />
+      </FieldGroup>
+      <FieldGroup label="Email" required helper="We'll never share your email">
+        <Input type="email" placeholder="john@example.com" />
+      </FieldGroup>
+      <FieldGroup label="Country">
+        <Select
+          options={['United States', 'Canada', 'United Kingdom']}
+          placeholder="Select country"
+        />
+      </FieldGroup>
+      <FieldGroup label="Bio" helper="Max 500 characters">
+        <Textarea placeholder="Tell us about yourself" />
+      </FieldGroup>
+      <FieldGroup marginBottom={0}>
+        <Button>Submit</Button>
+      </FieldGroup>
+    </div>
+  );
+}
+```
+
+### Field Group Sizes
+
+```tsx
+import * as React from 'react';
+import { FieldGroup } from '@xsolla/xui-field-group';
+import { Input } from '@xsolla/xui-input';
+
+export default function FieldGroupSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <FieldGroup size="sm" label="Small Field" required helper="Small helper">
+        <Input size="sm" placeholder="Small input" />
+      </FieldGroup>
+      <FieldGroup size="md" label="Medium Field" required helper="Medium helper">
+        <Input size="md" placeholder="Medium input" />
+      </FieldGroup>
+      <FieldGroup size="lg" label="Large Field" required helper="Large helper">
+        <Input size="lg" placeholder="Large input" />
+      </FieldGroup>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### FieldGroup
+
+**FieldGroup Props:**
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| children | `ReactNode` | - | Form field component. |
+| label | `string` | - | Label text. |
+| required | `boolean` | `false` | Show required asterisk (*). |
+| helper | `string` | - | Helper text below field. |
+| icon | `ReactElement` | - | Icon next to label. |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | Size variant. |
+| marginBottom | `number` | Based on size | Bottom margin for spacing. |
+| htmlFor | `string` | - | Associate label with field by ID. |
+| data-testid | `string` | - | Test identifier. |
+
+## Size Specifications
+
+| Size | Label Font | Label Line Height | Helper Font | Margin Bottom |
+| :--- | :--------- | :---------------- | :---------- | :------------ |
+| sm | 10px | 16px | 12px | 8px |
+| md | 12px | 20px | 12px | 16px |
+| lg | 14px | 24px | 12px | 24px |
+
+## Behavior
+
+- Required asterisk (*) appears before label in red
+- Icon appears after label with appropriate spacing
+- Helper text appears below the field content
+- Consistent vertical rhythm with configurable margins

package/package.json

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