Adds a component to support checkbox and radio groups

.changeset/afraid-tips-smile.md

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

.changeset/twenty-needles-sit.md

@@ -0,0 +1,5 @@
+---
+'@primer/components': minor
+---
+
+Adds ChoiceFieldset component

docs/content/Checkbox.md

@@ -2,7 +2,7 @@
 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'
 ---
 
@@ -12,6 +12,8 @@ import {ComponentChecklist} from '../src/component-checklist'
 
 The `Checkbox` component can be used in controlled and uncontrolled modes.
 
+**Use [CheckboxInputField](/CheckboxInputField) to render a checkbox with a label and other content related to the field.** Do not use this component on it's own unless you're rendering a "special" checkbox field that cannot be build using the `CheckboxInputField` component. For example: the "Use your administrator privilages..." checkbox at the bottom of PR that doesn't meet the criteria to be merged without admin privilages.
+
 ```jsx live
 <>
   <Box as="form" sx={{p: 3, pt: 0, display: 'flex', alignItems: 'center'}}>
@@ -116,3 +118,7 @@ items={{
     hasFigmaComponent: false
   }}
 />
+
+## Related components
+
+- [CheckboxInputField](/CheckboxInputField)

docs/content/CheckboxInputField.mdx

@@ -0,0 +1,156 @@
+---
+title: CheckboxInputField
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/CheckboxInputField.tsx
+storybook: '/react/storybook?path=/story/forms-checkboxinputfield--default'
+---
+
+import {ComponentChecklist} from '../src/component-checklist'
+
+<!--
+TODO: add `validationStatus` examples when we have the validation styling done
+-->
+
+import {CheckboxInputField} from '@primer/components'
+import {MarkGithubIcon} from '@primer/octicons-react'
+
+The `CheckboxInputField` component is used to render a labelled checkbox input and, optionally, associated hint text and graphic.
+
+**Use [ChoiceFieldset](/ChoiceFieldset) to render a group of related checkbox input fields.** Do not use this component on it's own unless you're rendering a single checkbox field on it's own, and there will never be related checkboxes.
+
+## Basic Example
+
+```jsx live
+<CheckboxInputField>
+  <CheckboxInputField.Label>Option one</CheckboxInputField.Label>
+  <CheckboxInputField.Input />
+</CheckboxInputField>
+```
+
+## CheckboxInputField
+
+The container that handles the layout and passes the relevant IDs and ARIA attributes it's children.
+
+`CheckboxInputField.Label` and `CheckboxInputField.Input` are required children.
+
+### Component props
+
+| Name       | Type                                                                                                                     |     Default      | Description                                                                                          |
+| :--------- | :----------------------------------------------------------------------------------------------------------------------- | :--------------: | :--------------------------------------------------------------------------------------------------- |
+| children\* | `CheckboxInputField.Label`, `CheckboxInputField.Input`, `CheckboxInputField.Caption`, `CheckboxInputField.LeadingVisual` |        -         | Required                                                                                             |
+| disabled   | `boolean`                                                                                                                |      false       | Whether the field is ready for user input                                                            |
+| id         | `string`                                                                                                                 | generated string | The unique identifier for this field. Used to associate the label, validation text, and caption text |
+
+### Example: disabled
+
+```jsx live
+<CheckboxInputField disabled>
+  <CheckboxInputField.Label>Option one</CheckboxInputField.Label>
+  <CheckboxInputField.Input />
+</CheckboxInputField>
+```
+
+## CheckboxInputField.Label
+
+A `CheckboxInputField.Label` must be passed, but it may be visually hidden.
+
+### Component props
+
+| Name           | Type      | Default | Description                                 |
+| :------------- | :-------- | :-----: | :------------------------------------------ |
+| visuallyHidden | `boolean` |  false  | Whether the label should be visually hidden |
+
+### Example: a visually hidden label
+
+```jsx live
+<CheckboxInputField>
+  <CheckboxInputField.Label visuallyHidden>Option One</CheckboxInputField.Label>
+  <CheckboxInputField.Input />
+</CheckboxInputField>
+```
+
+## CheckboxInputField.Input
+
+A [CheckboxInput](/CheckboxInput) will be rendered. This cannot be overridden
+
+### Component props
+
+The same props accepted by a [CheckboxInput](/CheckboxInput)
+
+## CheckboxInputField.Caption
+
+If this field needs additional context, a `CheckboxInputField.Caption` may be used to render hint text.
+
+### Component props
+
+| Name     | Type              | Default | Description                                                                              |
+| :------- | :---------------- | :-----: | :--------------------------------------------------------------------------------------- |
+| children | `React.ReactNode` |    -    | The content (usually just text) that is rendered to give contextual info about the field |
+
+### Example
+
+```jsx live
+<CheckboxInputField>
+  <CheckboxInputField.Label>Option One</CheckboxInputField.Label>
+  <CheckboxInputField.Input />
+  <CheckboxInputField.Caption>Hint: the first and only option</CheckboxInputField.Caption>
+</CheckboxInputField>
+```
+
+## CheckboxInputField.LeadingVisual
+
+If the selectable option would be easier to understand with a visual, the `CheckboxInputField.LeadingVisual` component may be used.
+
+### Component props
+
+| Name     | Type              | Default | Description                                      |
+| :------- | :---------------- | :-----: | :----------------------------------------------- |
+| children | `React.ReactNode` |    -    | The visual to render before the checkbox's label |
+
+### Example
+
+```jsx live
+<>
+  <CheckboxInputField>
+    <CheckboxInputField.Label>Option one</CheckboxInputField.Label>
+    <CheckboxInputField.LeadingVisual>
+      <MarkGithubIcon />
+    </CheckboxInputField.LeadingVisual>
+    <CheckboxInputField.Input />
+  </CheckboxInputField>
+
+  <CheckboxInputField>
+    <CheckboxInputField.Label>Option two</CheckboxInputField.Label>
+    <CheckboxInputField.LeadingVisual>
+      <MarkGithubIcon />
+    </CheckboxInputField.LeadingVisual>
+    <CheckboxInputField.Input />
+    <CheckboxInputField.Caption>This one has a caption</CheckboxInputField.Caption>
+  </CheckboxInputField>
+</>
+```
+
+## Component 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
+  }}
+/>
+
+## Related components
+
+- [ChoiceFieldset](/ChoiceFieldset)
+- [Checkbox](/Checkbox)