@bento/radio 0.1.2 → 0.1.3
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 +184 -0
- package/package.json +7 -6
package/README.md
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Radio
|
|
2
|
+
|
|
3
|
+
The `@bento/radio` package provides accessible, customizable radio controls. It exports the **RadioGroup** and **Radio** primitives, enabling you to build groups of radio options with consistent keyboard navigation, focus management, and ARIA support.
|
|
4
|
+
|
|
5
|
+
The `RadioGroup` allows a user to select a single item from a list of `Radio` components.
|
|
6
|
+
|
|
7
|
+
The `Radio` is a single radio option that can be selected by the user.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install --save @bento/radio
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
The `@bento/radio` package exports the `RadioGroup` and `Radio` primitives:
|
|
18
|
+
|
|
19
|
+
```jsx
|
|
20
|
+
import { RadioGroup, Radio } from '@bento/radio';
|
|
21
|
+
|
|
22
|
+
<RadioGroup label="Favorite fruit">
|
|
23
|
+
<Radio value="apple">Apple</Radio>
|
|
24
|
+
<Radio value="banana">Banana</Radio>
|
|
25
|
+
<Radio value="orange">Orange</Radio>
|
|
26
|
+
</RadioGroup>;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The following properties are available to be used on the `RadioGroup` and `Radio` primitives:
|
|
30
|
+
|
|
31
|
+
### RadioGroup
|
|
32
|
+
|
|
33
|
+
| Prop | Type | Required | Description |
|
|
34
|
+
|------|------|----------|------------|
|
|
35
|
+
| `value` | `string` | No | The current value (controlled). |
|
|
36
|
+
| `defaultValue` | `string` | No | The default value (uncontrolled). |
|
|
37
|
+
| `isDisabled` | `boolean` | No | Whether the input is disabled. |
|
|
38
|
+
| `isReadOnly` | `boolean` | No | Whether the input can be selected but not changed by the user. |
|
|
39
|
+
| `isRequired` | `boolean` | No | Whether user input is required on the input before form submission. |
|
|
40
|
+
| `isInvalid` | `boolean` | No | Whether the input value is invalid. |
|
|
41
|
+
| `name` | `string` | No | The name of the input element, used when submitting an HTML form. |
|
|
42
|
+
| `form` | `string` | No | The <form> element to associate the input with.
|
|
43
|
+
The value of this attribute must be the id of a <form> in the same document. |
|
|
44
|
+
| `children` | `ReactNode` | Yes | Radio children. |
|
|
45
|
+
| `errorMessage` | `ReactNode \| ((val: ValidationResult) => ReactNode)` | No | Error message for the radio group. |
|
|
46
|
+
| `slot` | `string` | No | A named part of a component that can be customized. This is implemented by the consuming component.
|
|
47
|
+
The exposed slot names of a component are available in the components documentation. |
|
|
48
|
+
| `labelProps` | `DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>` | No | Props to pass to the label element. |
|
|
49
|
+
| `descriptionProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | Props to pass to the description element. |
|
|
50
|
+
| `errorMessageProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | Props to pass to the error message element. |
|
|
51
|
+
| `contentProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | The props passed to the content element. |
|
|
52
|
+
| `slots` | `Record<string, object \| Function>` | No | An object that contains the customizations for the slots.
|
|
53
|
+
The main way you interact with the slot system as a consumer. |
|
|
54
|
+
|
|
55
|
+
### Radio
|
|
56
|
+
|
|
57
|
+
| Prop | Type | Required | Description |
|
|
58
|
+
|------|------|----------|------------|
|
|
59
|
+
| `value` | `string` | Yes | The value of the radio button, used when submitting an HTML form. |
|
|
60
|
+
| `inputRef` | `Ref<HTMLInputElement>` | No | A ref for the HTML input element. |
|
|
61
|
+
| `children` | `ReactNode` | No | The label for the Radio. Accepts any renderable node. |
|
|
62
|
+
| `isDisabled` | `boolean` | No | Whether the radio button is disabled or not. Shows that a selection exists,
|
|
63
|
+
but is not available in that circumstance. |
|
|
64
|
+
| `autoFocus` | `boolean` | No | Whether the element should receive focus on render. |
|
|
65
|
+
| `label` | `ReactNode` | No | The label for the control. |
|
|
66
|
+
| `slot` | `string` | No | A named part of a component that can be customized. This is implemented by the consuming component.
|
|
67
|
+
The exposed slot names of a component are available in the components documentation. |
|
|
68
|
+
| `inputProps` | `DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>` | No | Props to pass to the underlying input element. |
|
|
69
|
+
| `labelProps` | `DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>` | No | Props to pass to the label element. |
|
|
70
|
+
| `slots` | `Record<string, object \| Function>` | No | An object that contains the customizations for the slots.
|
|
71
|
+
The main way you interact with the slot system as a consumer. |
|
|
72
|
+
|
|
73
|
+
## Data Attributes, Slot Map and Props
|
|
74
|
+
|
|
75
|
+
The data attributes, slot map and props can be used to style and customize the `RadioGroup` and `Radio` primitives.
|
|
76
|
+
|
|
77
|
+
### `RadioGroup` Data Attributes
|
|
78
|
+
|
|
79
|
+
| Attribute | Description |
|
|
80
|
+
| --------------- | ------------------------------- |
|
|
81
|
+
| `data-disabled` | Indicates the group is disabled |
|
|
82
|
+
| `data-readonly` | Indicates the group is readonly |
|
|
83
|
+
| `data-required` | Indicates the group is required |
|
|
84
|
+
| `data-invalid` | Indicates the group is invalid |
|
|
85
|
+
|
|
86
|
+
### `Radio` Data Attributes
|
|
87
|
+
|
|
88
|
+
| Attribute | Description |
|
|
89
|
+
| -------------------- | ------------------------------------ |
|
|
90
|
+
| `data-pressed` | Indicates the radio is being pressed |
|
|
91
|
+
| `data-hovered` | Indicates the radio is hovered |
|
|
92
|
+
| `data-focused` | Indicates the radio has focus |
|
|
93
|
+
| `data-focus-visible` | Indicates focus should be visible |
|
|
94
|
+
| `data-selected` | Indicates the radio is selected |
|
|
95
|
+
| `data-disabled` | Indicates the radio is disabled |
|
|
96
|
+
| `data-readonly` | Indicates the radio is readonly |
|
|
97
|
+
| `data-invalid` | Indicates the radio is invalid |
|
|
98
|
+
| `data-required` | Indicates the radio is required |
|
|
99
|
+
|
|
100
|
+
### `RadioGroup` Slot Map
|
|
101
|
+
|
|
102
|
+
| Slot Name | Description |
|
|
103
|
+
| ------------------- | ---------------------------- |
|
|
104
|
+
| `group.label` | Label for radiogroup |
|
|
105
|
+
| `group.description` | Description for radiogroup |
|
|
106
|
+
| `group.error` | Error message for radiogroup |
|
|
107
|
+
|
|
108
|
+
### `Radio` Slot Map
|
|
109
|
+
|
|
110
|
+
| Slot Name | Description |
|
|
111
|
+
| ------------------------ | ------------------------ |
|
|
112
|
+
| `control.icon-checked` | Icon for checked radio |
|
|
113
|
+
| `control.icon-unchecked` | Icon for unchecked radio |
|
|
114
|
+
| `control.label` | Text for radio |
|
|
115
|
+
|
|
116
|
+
## Examples
|
|
117
|
+
|
|
118
|
+
### Uncontrolled
|
|
119
|
+
|
|
120
|
+
The `RadioGroup` is uncontrolled by default.
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
import { Radio, RadioGroup } from '@bento/radio';
|
|
124
|
+
/* v8 ignore next */
|
|
125
|
+
import React from 'react';
|
|
126
|
+
|
|
127
|
+
export function UncontrolledExample() {
|
|
128
|
+
return (
|
|
129
|
+
<RadioGroup label="Favorite fruit" onChange={(value: string) => console.log('selected', value)}>
|
|
130
|
+
<Radio value="apple">Apple</Radio>
|
|
131
|
+
<Radio value="banana">Banana</Radio>
|
|
132
|
+
<Radio value="orange" isDisabled>
|
|
133
|
+
Orange
|
|
134
|
+
</Radio>
|
|
135
|
+
</RadioGroup>
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Controlled
|
|
141
|
+
|
|
142
|
+
The `RadioGroup` can be controlled by passing a `value` and `onChange` prop.
|
|
143
|
+
|
|
144
|
+
```tsx
|
|
145
|
+
import { Radio, RadioGroup } from '@bento/radio';
|
|
146
|
+
/* v8 ignore next */
|
|
147
|
+
import React, { useState } from 'react';
|
|
148
|
+
|
|
149
|
+
export function ControlledExample() {
|
|
150
|
+
const [value, setValue] = useState<string>();
|
|
151
|
+
|
|
152
|
+
return (
|
|
153
|
+
<RadioGroup label="Favorite fruit" value={value} onChange={setValue}>
|
|
154
|
+
<Radio value="apple">Apple</Radio>
|
|
155
|
+
<Radio value="banana">Banana</Radio>
|
|
156
|
+
<Radio value="orange">Orange</Radio>
|
|
157
|
+
</RadioGroup>
|
|
158
|
+
);
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Single Radio
|
|
163
|
+
|
|
164
|
+
Even if you only have one radio option, it must always be placed inside a `RadioGroup`.
|
|
165
|
+
|
|
166
|
+
```tsx
|
|
167
|
+
import { Radio, RadioGroup } from '@bento/radio';
|
|
168
|
+
/* v8 ignore next */
|
|
169
|
+
import React, { type ComponentProps } from 'react';
|
|
170
|
+
|
|
171
|
+
export function SingleRadioExample(props: {
|
|
172
|
+
groupProps?: Partial<ComponentProps<typeof RadioGroup>>;
|
|
173
|
+
radioProps?: Partial<ComponentProps<typeof Radio>>;
|
|
174
|
+
}) {
|
|
175
|
+
return (
|
|
176
|
+
// Radios are always required to be in a group
|
|
177
|
+
<RadioGroup label="Favorite fruit (single radio)" name="fruit" {...props.groupProps}>
|
|
178
|
+
<Radio value="apple" {...props.radioProps}>
|
|
179
|
+
Apple
|
|
180
|
+
</Radio>
|
|
181
|
+
</RadioGroup>
|
|
182
|
+
);
|
|
183
|
+
}
|
|
184
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bento/radio",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Radio component",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"build": "tsup-node",
|
|
10
10
|
"lint": "biome lint && tsc",
|
|
11
11
|
"posttest": "npm run lint",
|
|
12
|
+
"prepublishOnly": "node ../../scripts/compile-readme.ts",
|
|
12
13
|
"pretest": "npm run build",
|
|
13
14
|
"test": "vitest --run",
|
|
14
15
|
"test:watch": "vitest"
|
|
@@ -39,11 +40,11 @@
|
|
|
39
40
|
"package.json"
|
|
40
41
|
],
|
|
41
42
|
"dependencies": {
|
|
42
|
-
"@bento/control": "^0.1.
|
|
43
|
-
"@bento/icon": "^0.1.
|
|
44
|
-
"@bento/slots": "^0.1.
|
|
45
|
-
"@bento/use-data-attributes": "^0.1.
|
|
46
|
-
"@bento/use-props": "^0.1.
|
|
43
|
+
"@bento/control": "^0.1.2",
|
|
44
|
+
"@bento/icon": "^0.1.2",
|
|
45
|
+
"@bento/slots": "^0.1.3",
|
|
46
|
+
"@bento/use-data-attributes": "^0.1.1",
|
|
47
|
+
"@bento/use-props": "^0.1.1",
|
|
47
48
|
"@react-aria/utils": "^3.30.0",
|
|
48
49
|
"react-aria": "^3.44.0",
|
|
49
50
|
"react-stately": "^3.42.0"
|