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,160 @@
+---
+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
+  }}
+/>