Input field components - text, checkbox, radio

.changeset/afraid-tips-smile.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Adds TextInputField, CheckboxInputField, and RadioInputField components. Also adds a few internal (private to primer/react) components to support form fields

docs/content/Checkbox.md

@@ -3,12 +3,21 @@ componentId: checkbox
 title: Checkbox
 description: Use checkboxes to toggle between checked and unchecked states in a list or as a standalone form field
 status: Alpha
-source: https://github.com/primer/react/blob/main/src/Checklist.tsx
+source: https://github.com/primer/react/blob/main/src/Checkbox.tsx
 storybook: '/react/storybook?path=/story/forms-checkbox--default'
 ---
 
 import {ComponentChecklist} from '../src/component-checklist'
 
+<Note variant="warning">
+
+**Use [ChoiceInputField](/ChoiceInputField) to display an accessible checkbox form field**. This `Checkbox` component is intended only as an ingredient for other custom components, or as a drop-in replacement for native HTML checkboxes outside of form use-cases.
+
+
+If you do use this component to build a custom checkbox, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.
+
+</Note>
+
 ## Default example
 
 The `Checkbox` component can be used in controlled and uncontrolled modes.
@@ -117,3 +126,7 @@ items={{
  hasFigmaComponent: false
  }}
 />
+
+## Related components
+
+- [CheckboxInputField](/CheckboxInputField)

docs/content/ChoiceInputField.mdx

@@ -0,0 +1,161 @@
+---
+componentId: choiceInputField
+title: ChoiceInputField
+status: Alpha
+description: The ChoiceInputField component is used to render a labelled checkbox or radio inputs with optional hint text.
+source: https://github.com/primer/react/blob/main/src/ChoiceInputField.tsx
+storybook: '/react/storybook?path=/story/forms-choiceinputfield--checkbox-input-field'
+---
+
+import {ChoiceInputField, Checkbox, Radio} from '@primer/react'
+import {MarkGithubIcon} from '@primer/octicons-react'
+import {PropsTable} from '../src/props-table'
+import {ComponentChecklist} from '../src/component-checklist'
+
+## Examples
+
+### Checkbox
+
+```jsx live
+<ChoiceInputField>
+ <ChoiceInputField.Label>Option one</ChoiceInputField.Label>
+ <Checkbox />
+</ChoiceInputField>
+```
+
+### Radio
+
+```jsx live
+<fieldset style={{margin: 0, padding: 0, border: 0}}>
+ <ChoiceInputField>
+ <ChoiceInputField.Label>Option one</ChoiceInputField.Label>
+ <Radio name="radioExample" value="one" />
+ </ChoiceInputField>
+ <ChoiceInputField>
+ <ChoiceInputField.Label>Option two</ChoiceInputField.Label>
+ <Radio name="radioExample" value="two" />
+ </ChoiceInputField>
+</fieldset>
+```
+
+### Disabled field
+
+```jsx live
+<ChoiceInputField disabled>
+ <ChoiceInputField.Label>Option one</ChoiceInputField.Label>
+ <Checkbox />
+</ChoiceInputField>
+```
+
+### With a caption
+
+```jsx live
+<ChoiceInputField>
+ <ChoiceInputField.Label>Option One</ChoiceInputField.Label>
+ <Checkbox />
+ <ChoiceInputField.Caption>Hint: the first and only option</ChoiceInputField.Caption>
+</ChoiceInputField>
+```
+
+### With a LeadingVisual
+
+```jsx live
+<>
+ <ChoiceInputField>
+ <ChoiceInputField.Label>Option one</ChoiceInputField.Label>
+ <ChoiceInputField.LeadingVisual>
+ <MarkGithubIcon />
+ </ChoiceInputField.LeadingVisual>
+ <Checkbox />
+ </ChoiceInputField>
+
+ <ChoiceInputField>
+ <ChoiceInputField.Label>Option two</ChoiceInputField.Label>
+ <ChoiceInputField.LeadingVisual>
+ <MarkGithubIcon />
+ </ChoiceInputField.LeadingVisual>
+ <Checkbox />
+ <ChoiceInputField.Caption>This one has a caption</ChoiceInputField.Caption>
+ </ChoiceInputField>
+</>
+```
+
+## Props
+
+### ChoiceInputField
+
+The container that handles the layout and passes the relevant IDs and ARIA attributes it's children.
+
+`ChoiceInputField.Label` and `ChoiceInputField.Input` are required children.
+
+<PropsTable>
+ <PropsTable.Row
+ name="children"
+ type="ChoiceInputField.Label | ChoiceInputField.Caption | ChoiceInputField.LeadingVisual | Checkbox | Radio"
+ required
+ />
+ <PropsTable.Row
+ name="disabled"
+ type="boolean"
+ defaultValue="false"
+ description="Whether the field is ready for user input"
+ />
+ <PropsTable.Row
+ name="id"
+ type="string"
+ defaultValue="a generated string"
+ description="The unique identifier for this field. Used to associate the label, validation text, and caption text"
+ />
+</PropsTable>
+
+### ChoiceInputField.Label
+
+A `ChoiceInputField.Label` must be passed, but it may be visually hidden.
+
+<PropsTable>
+ <PropsTable.Row name="children" type="React.ReactNode" description="The title that describes the choice input" />
+</PropsTable>
+
+### ChoiceInputField.Caption
+
+If this field needs additional context, a `ChoiceInputField.Caption` may be used to render hint text.
+
+<PropsTable>
+ <PropsTable.Row
+ name="children"
+ type="React.ReactNode"
+ description="The content (usually just text) that is rendered to give contextual info about the field"
+ />
+</PropsTable>
+
+### ChoiceInputField.LeadingVisual
+
+If the selectable option would be easier to understand with a visual, the `ChoiceInputField.LeadingVisual` component may be used.
+
+<PropsTable>
+ <PropsTable.Row
+ name="children"
+ type="React.ReactNode"
+ description="The visual to render before the choice input's label"
+ />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+ items={{
+ propsDocumented: true,
+ noUnnecessaryDeps: true,
+ adaptsToThemes: true,
+ adaptsToScreenSizes: true,
+ fullTestCoverage: true,
+ usedInProduction: false,
+ usageExamplesDocumented: true,
+ designReviewed: false,
+ a11yReviewed: true,
+ stableApi: false,
+ addressedApiFeedback: false,
+ hasDesignGuidelines: false,
+ hasFigmaComponent: false
+ }}
+/>