@xsolla/xui-checkbox 0.99.0 → 0.100.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.
- package/README.md +277 -16
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,37 +1,298 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Checkbox
|
|
3
|
+
subtitle: A checkbox for boolean selection.
|
|
4
|
+
description: A cross-platform React checkbox component with label, description, indeterminate state, and validation support.
|
|
5
|
+
---
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
# Checkbox
|
|
8
|
+
|
|
9
|
+
A cross-platform React checkbox component with label, description, indeterminate state, and validation support. Works on both React (web) and React Native.
|
|
4
10
|
|
|
5
11
|
## Installation
|
|
6
12
|
|
|
7
13
|
```bash
|
|
14
|
+
npm install @xsolla/xui-checkbox
|
|
15
|
+
# or
|
|
8
16
|
yarn add @xsolla/xui-checkbox
|
|
9
17
|
```
|
|
10
18
|
|
|
11
|
-
##
|
|
19
|
+
## Demo
|
|
20
|
+
|
|
21
|
+
### Basic Checkbox
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import * as React from 'react';
|
|
25
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
26
|
+
|
|
27
|
+
export default function BasicCheckbox() {
|
|
28
|
+
const [checked, setChecked] = React.useState(false);
|
|
29
|
+
|
|
30
|
+
return (
|
|
31
|
+
<Checkbox
|
|
32
|
+
checked={checked}
|
|
33
|
+
onChange={(e) => setChecked(e.target.checked)}
|
|
34
|
+
>
|
|
35
|
+
Accept terms and conditions
|
|
36
|
+
</Checkbox>
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Checkbox with Description
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
import * as React from 'react';
|
|
45
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
46
|
+
|
|
47
|
+
export default function CheckboxWithDescription() {
|
|
48
|
+
const [checked, setChecked] = React.useState(false);
|
|
49
|
+
|
|
50
|
+
return (
|
|
51
|
+
<Checkbox
|
|
52
|
+
checked={checked}
|
|
53
|
+
onChange={(e) => setChecked(e.target.checked)}
|
|
54
|
+
description="You will receive notifications about updates and promotions"
|
|
55
|
+
>
|
|
56
|
+
Subscribe to newsletter
|
|
57
|
+
</Checkbox>
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Checkbox Sizes
|
|
12
63
|
|
|
13
64
|
```tsx
|
|
65
|
+
import * as React from 'react';
|
|
66
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
67
|
+
|
|
68
|
+
export default function CheckboxSizes() {
|
|
69
|
+
return (
|
|
70
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
|
|
71
|
+
<Checkbox size="sm">Small checkbox</Checkbox>
|
|
72
|
+
<Checkbox size="md">Medium checkbox (default)</Checkbox>
|
|
73
|
+
<Checkbox size="lg">Large checkbox</Checkbox>
|
|
74
|
+
<Checkbox size="xl">Extra large checkbox</Checkbox>
|
|
75
|
+
</div>
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Indeterminate State
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
import * as React from 'react';
|
|
84
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
85
|
+
|
|
86
|
+
export default function IndeterminateCheckbox() {
|
|
87
|
+
const [items, setItems] = React.useState([
|
|
88
|
+
{ id: 1, label: 'Item 1', checked: true },
|
|
89
|
+
{ id: 2, label: 'Item 2', checked: false },
|
|
90
|
+
{ id: 3, label: 'Item 3', checked: true },
|
|
91
|
+
]);
|
|
92
|
+
|
|
93
|
+
const allChecked = items.every((item) => item.checked);
|
|
94
|
+
const someChecked = items.some((item) => item.checked);
|
|
95
|
+
|
|
96
|
+
const handleSelectAll = () => {
|
|
97
|
+
setItems(items.map((item) => ({ ...item, checked: !allChecked })));
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
return (
|
|
101
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
|
|
102
|
+
<Checkbox
|
|
103
|
+
checked={allChecked}
|
|
104
|
+
indeterminate={someChecked && !allChecked}
|
|
105
|
+
onChange={handleSelectAll}
|
|
106
|
+
>
|
|
107
|
+
Select all
|
|
108
|
+
</Checkbox>
|
|
109
|
+
<div style={{ marginLeft: 24, display: 'flex', flexDirection: 'column', gap: 8 }}>
|
|
110
|
+
{items.map((item) => (
|
|
111
|
+
<Checkbox
|
|
112
|
+
key={item.id}
|
|
113
|
+
checked={item.checked}
|
|
114
|
+
onChange={(e) => {
|
|
115
|
+
setItems(items.map((i) =>
|
|
116
|
+
i.id === item.id ? { ...i, checked: e.target.checked } : i
|
|
117
|
+
));
|
|
118
|
+
}}
|
|
119
|
+
>
|
|
120
|
+
{item.label}
|
|
121
|
+
</Checkbox>
|
|
122
|
+
))}
|
|
123
|
+
</div>
|
|
124
|
+
</div>
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Anatomy
|
|
130
|
+
|
|
131
|
+
Import the component and use it directly:
|
|
132
|
+
|
|
133
|
+
```jsx
|
|
14
134
|
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
15
135
|
|
|
16
136
|
<Checkbox
|
|
17
|
-
checked={
|
|
18
|
-
onChange={
|
|
137
|
+
checked={checked} // Controlled checked state
|
|
138
|
+
onChange={handleChange} // Change handler
|
|
139
|
+
indeterminate={false} // Indeterminate/mixed state
|
|
140
|
+
size="md" // Size variant
|
|
141
|
+
description="Help text" // Description below label
|
|
142
|
+
errorMessage="Error text" // Error message
|
|
143
|
+
disabled={false} // Disabled state
|
|
19
144
|
>
|
|
20
|
-
|
|
145
|
+
Label text
|
|
21
146
|
</Checkbox>
|
|
22
147
|
```
|
|
23
148
|
|
|
24
|
-
##
|
|
149
|
+
## Examples
|
|
150
|
+
|
|
151
|
+
### Error State
|
|
152
|
+
|
|
153
|
+
```tsx
|
|
154
|
+
import * as React from 'react';
|
|
155
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
156
|
+
|
|
157
|
+
export default function ErrorCheckbox() {
|
|
158
|
+
return (
|
|
159
|
+
<Checkbox
|
|
160
|
+
checked={false}
|
|
161
|
+
errorMessage="You must accept the terms to continue"
|
|
162
|
+
>
|
|
163
|
+
I accept the terms and conditions
|
|
164
|
+
</Checkbox>
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Disabled Checkbox
|
|
170
|
+
|
|
171
|
+
```tsx
|
|
172
|
+
import * as React from 'react';
|
|
173
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
174
|
+
|
|
175
|
+
export default function DisabledCheckbox() {
|
|
176
|
+
return (
|
|
177
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
|
|
178
|
+
<Checkbox disabled>Disabled unchecked</Checkbox>
|
|
179
|
+
<Checkbox disabled checked>Disabled checked</Checkbox>
|
|
180
|
+
</div>
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Form Integration
|
|
186
|
+
|
|
187
|
+
```tsx
|
|
188
|
+
import * as React from 'react';
|
|
189
|
+
import { Checkbox } from '@xsolla/xui-checkbox';
|
|
190
|
+
import { Button } from '@xsolla/xui-button';
|
|
191
|
+
|
|
192
|
+
export default function FormCheckbox() {
|
|
193
|
+
const [preferences, setPreferences] = React.useState({
|
|
194
|
+
marketing: false,
|
|
195
|
+
updates: true,
|
|
196
|
+
newsletter: false,
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
const handleChange = (key: string) => (e: { target: { checked: boolean } }) => {
|
|
200
|
+
setPreferences((prev) => ({ ...prev, [key]: e.target.checked }));
|
|
201
|
+
};
|
|
202
|
+
|
|
203
|
+
return (
|
|
204
|
+
<form onSubmit={(e) => { e.preventDefault(); console.log(preferences); }}>
|
|
205
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
|
|
206
|
+
<Checkbox
|
|
207
|
+
name="marketing"
|
|
208
|
+
checked={preferences.marketing}
|
|
209
|
+
onChange={handleChange('marketing')}
|
|
210
|
+
>
|
|
211
|
+
Receive marketing emails
|
|
212
|
+
</Checkbox>
|
|
213
|
+
<Checkbox
|
|
214
|
+
name="updates"
|
|
215
|
+
checked={preferences.updates}
|
|
216
|
+
onChange={handleChange('updates')}
|
|
217
|
+
>
|
|
218
|
+
Receive product updates
|
|
219
|
+
</Checkbox>
|
|
220
|
+
<Checkbox
|
|
221
|
+
name="newsletter"
|
|
222
|
+
checked={preferences.newsletter}
|
|
223
|
+
onChange={handleChange('newsletter')}
|
|
224
|
+
>
|
|
225
|
+
Subscribe to newsletter
|
|
226
|
+
</Checkbox>
|
|
227
|
+
<Button type="submit">Save Preferences</Button>
|
|
228
|
+
</div>
|
|
229
|
+
</form>
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## API Reference
|
|
25
235
|
|
|
26
236
|
### Checkbox
|
|
27
237
|
|
|
238
|
+
The main checkbox component with label support.
|
|
239
|
+
|
|
240
|
+
**Checkbox Props:**
|
|
241
|
+
|
|
28
242
|
| Prop | Type | Default | Description |
|
|
29
|
-
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
243
|
+
| :--- | :--- | :------ | :---------- |
|
|
244
|
+
| children | `ReactNode` | - | Label content displayed next to the checkbox. |
|
|
245
|
+
| checked | `boolean` | `false` | Whether the checkbox is checked. |
|
|
246
|
+
| indeterminate | `boolean` | `false` | Whether to show indeterminate (mixed) state. |
|
|
247
|
+
| size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the checkbox. |
|
|
248
|
+
| disabled | `boolean` | `false` | Whether the checkbox is disabled. |
|
|
249
|
+
| description | `string` | - | Description text displayed below the label. |
|
|
250
|
+
| errorMessage | `string` | - | Error message displayed below (shows error styling). |
|
|
251
|
+
| error | `boolean` | `false` | Show error styling without message. |
|
|
252
|
+
| name | `string` | - | HTML name attribute for form submission. |
|
|
253
|
+
| value | `string` | - | HTML value attribute for form submission. |
|
|
254
|
+
| onChange | `(e: { target: { checked: boolean; name?: string; value?: string } }) => void` | - | Change event handler. |
|
|
255
|
+
| id | `string` | - | HTML id attribute. |
|
|
256
|
+
| aria-label | `string` | - | Accessible label for screen readers. |
|
|
257
|
+
|
|
258
|
+
**Checkbox Ref Methods:**
|
|
259
|
+
|
|
260
|
+
| Method | Description |
|
|
261
|
+
| :----- | :---------- |
|
|
262
|
+
| `focus()` | Programmatically focus the checkbox. |
|
|
263
|
+
| `blur()` | Programmatically blur the checkbox. |
|
|
264
|
+
|
|
265
|
+
**Size Configuration:**
|
|
266
|
+
|
|
267
|
+
| Size | Checkbox | Icon | Font Size | Line Height |
|
|
268
|
+
| :--- | :------- | :--- | :-------- | :---------- |
|
|
269
|
+
| sm | 16px | 12px | 14px | 16px |
|
|
270
|
+
| md | 18px | 14px | 16px | 18px |
|
|
271
|
+
| lg | 20px | 16px | 18px | 20px |
|
|
272
|
+
| xl | 22px | 18px | 18px | 22px |
|
|
273
|
+
|
|
274
|
+
## Theming
|
|
275
|
+
|
|
276
|
+
Checkbox uses the design system theme for colors:
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
// Colors accessed via theme
|
|
280
|
+
theme.colors.control.checkbox.bg // Unchecked background
|
|
281
|
+
theme.colors.control.checkbox.bgChecked // Checked background
|
|
282
|
+
theme.colors.control.checkbox.border // Border color
|
|
283
|
+
theme.colors.control.checkbox.borderChecked // Checked border
|
|
284
|
+
theme.colors.control.checkbox.check // Checkmark color
|
|
285
|
+
theme.colors.content.primary // Label text
|
|
286
|
+
theme.colors.content.secondary // Description text
|
|
287
|
+
theme.colors.content.error // Error text
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
## Accessibility
|
|
291
|
+
|
|
292
|
+
- Uses semantic checkbox input with proper labeling
|
|
293
|
+
- Supports keyboard navigation (Tab to focus, Space/Enter to toggle)
|
|
294
|
+
- `aria-checked` reflects current state including "mixed" for indeterminate
|
|
295
|
+
- `aria-invalid` set when in error state
|
|
296
|
+
- `aria-describedby` links to error/description text
|
|
297
|
+
- Focus indicator follows WCAG guidelines
|
|
298
|
+
- Disabled state properly announced to assistive technology
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xsolla/xui-checkbox",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.100.0",
|
|
4
4
|
"main": "./web/index.js",
|
|
5
5
|
"module": "./web/index.mjs",
|
|
6
6
|
"types": "./web/index.d.ts",
|
|
@@ -13,9 +13,9 @@
|
|
|
13
13
|
"test:coverage": "vitest run --coverage"
|
|
14
14
|
},
|
|
15
15
|
"dependencies": {
|
|
16
|
-
"@xsolla/xui-core": "0.
|
|
17
|
-
"@xsolla/xui-icons": "0.
|
|
18
|
-
"@xsolla/xui-primitives-core": "0.
|
|
16
|
+
"@xsolla/xui-core": "0.100.0",
|
|
17
|
+
"@xsolla/xui-icons": "0.100.0",
|
|
18
|
+
"@xsolla/xui-primitives-core": "0.100.0"
|
|
19
19
|
},
|
|
20
20
|
"peerDependencies": {
|
|
21
21
|
"react": ">=16.8.0",
|