@xsolla/xui-supporting-text 0.150.0 → 0.152.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +88 -164
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,243 +1,167 @@
1
- # Supporting Text
1
+ # SupportingText
2
2
 
3
- A cross-platform React component for displaying supporting text around form fields, including labels, helper text, descriptions, and error messages with proper accessibility.
3
+ A small, accessible text component for labels, helpers, descriptions, and error messages around form fields.
4
4
 
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
8
  npm install @xsolla/xui-supporting-text
9
- # or
10
- yarn add @xsolla/xui-supporting-text
11
9
  ```
12
10
 
13
- ## Demo
14
-
15
- ### All Variants
11
+ ## Imports
16
12
 
17
13
  ```tsx
18
- import * as React from 'react';
19
14
  import { SupportingText } from '@xsolla/xui-supporting-text';
20
-
21
- export default function AllVariants() {
22
- return (
23
- <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
24
- <SupportingText variant="label">Label text</SupportingText>
25
- <SupportingText variant="helper">Helper text with guidance</SupportingText>
26
- <SupportingText variant="description">Description text for context</SupportingText>
27
- <SupportingText variant="error">Error message</SupportingText>
28
- </div>
29
- );
30
- }
31
15
  ```
32
16
 
33
- ### Different Sizes
17
+ ## Quick start
34
18
 
35
19
  ```tsx
36
20
  import * as React from 'react';
37
21
  import { SupportingText } from '@xsolla/xui-supporting-text';
38
22
 
39
- export default function Sizes() {
40
- return (
41
- <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
42
- <SupportingText size="xs">Extra small</SupportingText>
43
- <SupportingText size="sm">Small</SupportingText>
44
- <SupportingText size="md">Medium</SupportingText>
45
- <SupportingText size="lg">Large</SupportingText>
46
- <SupportingText size="xl">Extra large</SupportingText>
47
- </div>
48
- );
23
+ export default function QuickStart() {
24
+ return <SupportingText variant="helper">Helper text</SupportingText>;
49
25
  }
50
26
  ```
51
27
 
52
- ### With Icon
28
+ ## API Reference
53
29
 
54
- ```tsx
55
- import * as React from 'react';
56
- import { SupportingText } from '@xsolla/xui-supporting-text';
57
- import { Info } from '@xsolla/xui-icons-base';
30
+ ### `<SupportingText>`
58
31
 
59
- export default function WithIcon() {
60
- return (
61
- <SupportingText variant="helper" icon={<Info />} showIcon>
62
- Click here for more information
63
- </SupportingText>
64
- );
65
- }
66
- ```
32
+ | Prop | Type | Default | Description |
33
+ | --- | --- | --- | --- |
34
+ | `children` | `ReactNode` | - | Text content. |
35
+ | `variant` | `"label" \| "helper" \| "description" \| "error"` | `"helper"` | Visual variant. Only `error` changes colour and announcement behaviour. |
36
+ | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Sizing token; resolves font size, line height, gap, and icon size via `theme.sizing.supportingText`. |
37
+ | `icon` | `ReactNode` | - | Icon rendered after the text. |
38
+ | `showIcon` | `boolean` | `false` | Render the icon slot. The icon is also rendered when `icon` is provided. |
39
+ | `id` | `string` | - | HTML id for `aria-describedby` linking. |
40
+ | `aria-label` | `string` | - | Accessible label override. |
41
+ | `aria-describedby` | `string` | - | Id of an element this text describes. |
42
+ | `testID` | `string` | - | Test identifier. |
43
+
44
+ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
67
45
 
68
46
  ## Anatomy
69
47
 
70
- ```jsx
48
+ ```tsx
71
49
  import { SupportingText } from '@xsolla/xui-supporting-text';
50
+ import { Info } from '@xsolla/xui-icons-base';
72
51
 
73
52
  <SupportingText
74
- variant="helper" // label, helper, description, error
75
- size="md" // xs, s, m, l, xl
76
- icon={<Icon />} // Optional icon
77
- showIcon={true} // Show icon
78
- id="field-hint" // ID for aria-describedby
79
- aria-label="Hint" // Accessible label
53
+ variant="helper"
54
+ size="md"
55
+ icon={<Info />}
56
+ showIcon
57
+ id="field-hint"
80
58
  >
81
- Helper text content
59
+ Helper content
82
60
  </SupportingText>
83
61
  ```
84
62
 
63
+ ## Variants
64
+
65
+ | Variant | Colour | Usage |
66
+ | --- | --- | --- |
67
+ | `label` | `content.tertiary` | Field labels. |
68
+ | `helper` | `content.tertiary` | Inline guidance and hints. |
69
+ | `description` | `content.tertiary` | Additional context below a control. |
70
+ | `error` | `content.alert.primary` | Validation errors. Adds `role="alert"` and `aria-live="polite"`. |
71
+
85
72
  ## Examples
86
73
 
87
- ### Form Field with Label and Error
74
+ ### All variants
88
75
 
89
76
  ```tsx
90
77
  import * as React from 'react';
91
78
  import { SupportingText } from '@xsolla/xui-supporting-text';
92
- import { Input } from '@xsolla/xui-input';
93
-
94
- export default function FormField() {
95
- const [email, setEmail] = React.useState('');
96
- const [error, setError] = React.useState('');
97
-
98
- const validate = (value: string) => {
99
- if (value && !value.includes('@')) {
100
- setError('Please enter a valid email address');
101
- } else {
102
- setError('');
103
- }
104
- };
105
79
 
80
+ export default function Variants() {
106
81
  return (
107
- <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
108
- <SupportingText variant="label" id="email-label">
109
- Email address
110
- </SupportingText>
111
- <Input
112
- value={email}
113
- onChangeText={(text) => {
114
- setEmail(text);
115
- validate(text);
116
- }}
117
- aria-labelledby="email-label"
118
- aria-describedby={error ? 'email-error' : 'email-hint'}
119
- error={!!error}
120
- />
121
- {error ? (
122
- <SupportingText variant="error" id="email-error">
123
- {error}
124
- </SupportingText>
125
- ) : (
126
- <SupportingText variant="helper" id="email-hint">
127
- We'll never share your email
128
- </SupportingText>
129
- )}
82
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
83
+ <SupportingText variant="label">Label</SupportingText>
84
+ <SupportingText variant="helper">Helper</SupportingText>
85
+ <SupportingText variant="description">Description</SupportingText>
86
+ <SupportingText variant="error">Error message</SupportingText>
130
87
  </div>
131
88
  );
132
89
  }
133
90
  ```
134
91
 
135
- ### Password Requirements
92
+ ### Sizes
136
93
 
137
94
  ```tsx
138
95
  import * as React from 'react';
139
96
  import { SupportingText } from '@xsolla/xui-supporting-text';
140
- import { InputPassword } from '@xsolla/xui-input-password';
141
97
 
142
- export default function PasswordField() {
98
+ export default function Sizes() {
143
99
  return (
144
- <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
145
- <SupportingText variant="label">Password</SupportingText>
146
- <InputPassword extraSee />
147
- <SupportingText variant="description" size="sm">
148
- Password must contain at least 8 characters, including uppercase, lowercase, and numbers.
149
- </SupportingText>
100
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
101
+ <SupportingText size="xs">xs</SupportingText>
102
+ <SupportingText size="sm">sm</SupportingText>
103
+ <SupportingText size="md">md</SupportingText>
104
+ <SupportingText size="lg">lg</SupportingText>
105
+ <SupportingText size="xl">xl</SupportingText>
150
106
  </div>
151
107
  );
152
108
  }
153
109
  ```
154
110
 
155
- ### Character Count Helper
111
+ ### With icon
156
112
 
157
113
  ```tsx
158
114
  import * as React from 'react';
159
115
  import { SupportingText } from '@xsolla/xui-supporting-text';
160
- import { Textarea } from '@xsolla/xui-textarea';
161
-
162
- export default function CharacterCount() {
163
- const [text, setText] = React.useState('');
164
- const maxLength = 280;
165
- const isOverLimit = text.length > maxLength;
116
+ import { Info } from '@xsolla/xui-icons-base';
166
117
 
118
+ export default function WithIcon() {
167
119
  return (
168
- <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
169
- <SupportingText variant="label">Bio</SupportingText>
170
- <Textarea
171
- value={text}
172
- onChangeText={setText}
173
- placeholder="Tell us about yourself"
174
- />
175
- <SupportingText
176
- variant={isOverLimit ? 'error' : 'helper'}
177
- size="sm"
178
- >
179
- {text.length}/{maxLength} characters
180
- </SupportingText>
181
- </div>
120
+ <SupportingText variant="helper" icon={<Info />} showIcon>
121
+ Click here for more information
122
+ </SupportingText>
182
123
  );
183
124
  }
184
125
  ```
185
126
 
186
- ### Field Group with Description
127
+ ### Form field with linked error
187
128
 
188
129
  ```tsx
189
130
  import * as React from 'react';
190
131
  import { SupportingText } from '@xsolla/xui-supporting-text';
191
- import { Checkbox } from '@xsolla/xui-checkbox';
132
+ import { Input } from '@xsolla/xui-input';
133
+
134
+ export default function LinkedError() {
135
+ const [email, setEmail] = React.useState('');
136
+ const [error, setError] = React.useState('');
137
+
138
+ const validate = (value: string) => {
139
+ setError(value && !value.includes('@') ? 'Please enter a valid email address' : '');
140
+ };
192
141
 
193
- export default function FieldGroup() {
194
142
  return (
195
- <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
196
- <SupportingText variant="label">Notification preferences</SupportingText>
197
- <SupportingText variant="description" size="sm">
198
- Choose how you'd like to receive updates from us
199
- </SupportingText>
200
- <div style={{ display: 'flex', flexDirection: 'column', gap: 4, marginTop: 8 }}>
201
- <Checkbox label="Email notifications" />
202
- <Checkbox label="Push notifications" />
203
- <Checkbox label="SMS notifications" />
204
- </div>
143
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
144
+ <SupportingText variant="label" id="email-label">Email</SupportingText>
145
+ <Input
146
+ value={email}
147
+ onChangeText={(text) => { setEmail(text); validate(text); }}
148
+ aria-labelledby="email-label"
149
+ aria-describedby={error ? 'email-error' : 'email-hint'}
150
+ error={!!error}
151
+ />
152
+ {error ? (
153
+ <SupportingText variant="error" id="email-error">{error}</SupportingText>
154
+ ) : (
155
+ <SupportingText variant="helper" id="email-hint">We'll never share your email</SupportingText>
156
+ )}
205
157
  </div>
206
158
  );
207
159
  }
208
160
  ```
209
161
 
210
- ## API Reference
211
-
212
- ### SupportingText
213
-
214
- **SupportingTextProps:**
215
-
216
- | Prop | Type | Default | Description |
217
- | :--- | :--- | :------ | :---------- |
218
- | children | `ReactNode` | - | Text content to display. |
219
- | variant | `"label" \| "helper" \| "description" \| "error"` | `"helper"` | Visual variant. |
220
- | size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Text size. |
221
- | icon | `ReactNode` | - | Icon to display after text. |
222
- | showIcon | `boolean` | `false` | Whether to show the icon. |
223
- | id | `string` | - | HTML id for accessibility linking. |
224
- | aria-label | `string` | - | Accessible label. |
225
- | aria-describedby | `string` | - | ID of element this text describes. |
226
- | testID | `string` | - | Test identifier. |
227
-
228
- ## Variants
229
-
230
- | Variant | Color | Use Case |
231
- | :------ | :---- | :------- |
232
- | `label` | Primary | Field labels |
233
- | `helper` | Tertiary | Guidance and hints |
234
- | `description` | Tertiary | Additional context |
235
- | `error` | Alert | Validation errors |
236
-
237
- ## Accessibility Features
162
+ ## Accessibility
238
163
 
239
- - **Error variant**: Uses `role="alert"` for immediate announcement
240
- - **Live regions**: Error messages use `aria-live="polite"`
241
- - **ID linking**: Use `id` with `aria-describedby` on form fields
242
- - **Color contrast**: Appropriate colors for all variants
243
- - **Icon handling**: Icons are hidden from screen readers
164
+ - The `error` variant renders with `role="alert"` and `aria-live="polite"` so messages are announced when they appear.
165
+ - The explicit `aria-live="polite"` intentionally overrides the implicit `assertive` that `role="alert"` would otherwise apply, so error messages announce without interrupting the user's current screen reader output.
166
+ - Use `id` on the supporting text and reference it from the related form control's `aria-describedby` so the text is read together with the field.
167
+ - Icons rendered through the `icon`/`showIcon` props are marked `aria-hidden`; pair with descriptive text rather than relying on iconography alone.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-supporting-text",
3
- "version": "0.150.0",
3
+ "version": "0.152.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -10,9 +10,9 @@
10
10
  "build:native": "PLATFORM=native tsup"
11
11
  },
12
12
  "dependencies": {
13
- "@xsolla/xui-core": "0.150.0",
14
- "@xsolla/xui-icons": "0.150.0",
15
- "@xsolla/xui-primitives-core": "0.150.0"
13
+ "@xsolla/xui-core": "0.152.0",
14
+ "@xsolla/xui-icons": "0.152.0",
15
+ "@xsolla/xui-primitives-core": "0.152.0"
16
16
  },
17
17
  "peerDependencies": {
18
18
  "react": ">=16.8.0",