Deprecate components replaced by FormControl

.changeset/olive-bears-act.md

@@ -0,0 +1,107 @@
+---
+'@primer/react': major
+---
+
+![image](https://user-images.githubusercontent.com/13340707/154948443-60d70cc7-4f26-444f-8366-7963336be53c.png)
+
+The `FormControl` component will be used to deprecate the `FormGroup`, `InputField`, and `ChoiceInputField` components. It has the ability to render contextual content with your inputs: labels, validation statuses, captions. It also handles the ARIA attributes that make the form controls accessible to assistive technology.
+
+<table>
+<tr>
+<th> Before </th> <th> After </th>
+</tr>
+<tr>
+<td valign="top">
+
+```jsx
+import {FormControl, Checkbox, TextInput} from "@primer/react"
+
+
+<FormGroup>
+    <FormGroup.Label htmlFor="example-text">Example text</FormGroup.Label>
+    <TextInput id="example-text" />
+</FormGroup>
+
+OR
+
+<InputField>
+    <InputField.Label>Example text</InputField.Label>
+    <TextInput />
+</InputField>
+
+OR
+
+<ChoiceInputField>
+    <ChoiceInputField.Label>Example text</ChoiceInputField.Label>
+    <Checkbox />
+</ChoiceInputField>
+
+```
+
+</td>
+<td valign="top">
+
+```jsx
+import {FormGroup, TextInput} from "@primer/react"
+
+<FormControl>
+  <FormControl.Label>Example text</FormControl.Label>
+  <TextInput />
+</FormControl>
+
+OR
+
+<FormControl>
+  <FormControl.Label>Example text</FormControl.Label>
+  <Checkbox />
+</FormControl>
+
+```
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+```jsx
+import {InputField} from '@primer/react'
+
+;<InputField>
+  <InputField.Label>Example text</InputField.Label>
+  <TextInput />
+</InputField>
+```
+
+</td>
+<td valign="top">
+
+```jsx
+import {FormControl} from '@primer/react'
+
+;<FormControl>
+  <FormControl.Label>Example Text</FormControl.Label>
+  <TextInput />
+</FormControl>
+```
+
+</td>
+</tr>
+</table>
+<table style="display: table">
+<tr><th>Migration steps to FormControl</th></tr>
+<tr>
+<td>
+
+<strong>Upgrade to the new</strong> `FormControl` component by referring to the [examples in our documentation](https://primer.style/react/FormControl).
+
+or
+
+<strong>Continue using the deprecated</strong> `FormGroup`, `ChoiceInputField` or `InputField` :
+
+```js
+import {FormGroup, ChoiceInputField, InputField} from '@primer/react/deprecated' // change your import statements
+```
+
+</td>
+</tr>
+</table>

docs/content/InputField.mdx

@@ -7,7 +7,7 @@ source: https://github.com/primer/react/blob/main/src/InputField/InputField.tsx
 storybook: '/react/storybook?path=/story/forms-inputfield--text-input-field'
 ---
 
-import {InputField, TextInputWithTokens, Autocomplete, Select} from '@primer/react'
+import {TextInputWithTokens, Autocomplete, Select} from '@primer/react'
 
 ## Deprecation
 
@@ -17,7 +17,7 @@ Use [FormControl](/FormControl) instead.
 
 ### Basic
 
-```jsx live
+```jsx live deprecated
 <InputField>
   <InputField.Label>Name</InputField.Label>
   <TextInput />
@@ -26,7 +26,7 @@ Use [FormControl](/FormControl) instead.
 
 ### Required
 
-```jsx live
+```jsx live deprecated
 <InputField required>
   <InputField.Label>Name</InputField.Label>
   <TextInput />
@@ -35,7 +35,7 @@ Use [FormControl](/FormControl) instead.
 
 ### Disabled
 
-```jsx live
+```jsx live deprecated
 <InputField disabled>
   <InputField.Label>Name</InputField.Label>
   <TextInput />
@@ -44,7 +44,7 @@ Use [FormControl](/FormControl) instead.
 
 ### Using different input components
 
-```javascript live noinline
+```javascript live noinline deprecated
 const TextInputWithTokensExample = () => {
   const [tokens, setTokens] = React.useState([
     {text: 'zero', id: 0},
@@ -115,7 +115,7 @@ Every input must have a corresponding label to be accessible to assistive techno
 
 </Note>
 
-```jsx live
+```jsx live deprecated
 <InputField>
   <InputField.Label visuallyHidden>Name</InputField.Label>
   <TextInput />
@@ -124,7 +124,7 @@ Every input must have a corresponding label to be accessible to assistive techno
 
 ### With a caption
 
-```jsx live
+```jsx live deprecated
 <InputField>
   <InputField.Label>Name</InputField.Label>
   <TextInput />
@@ -134,7 +134,7 @@ Every input must have a corresponding label to be accessible to assistive techno
 
 ### With validation
 
-```javascript live noinline
+```javascript live noinline deprecated
 const ValidationExample = () => {
   const [value, setValue] = React.useState('mona lisa')
   const [validationResult, setValidationResult] = React.useState()

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -161,5 +161,7 @@
       url: /deprecated/Dropdown
     - title: FormGroup
       url: /FormGroup
+    - title: InputField
+      url: /deprecated/InputField
     - title: SelectMenu
       url: /deprecated/SelectMenu

src/FormGroup.tsx

@@ -3,12 +3,14 @@ import {get} from './constants'
 import sx, {SxProp} from './sx'
 import {ComponentProps} from './utils/types'
 
+/** @deprecated Use FormControl instead. See https://primer.style/react/FormControl for more details. */
 const FormGroup = styled.div<SxProp>`
   margin: ${get('space.3')} 0;
   font-weight: ${get('fontWeights.normal')};
   ${sx};
 `
 
+/** @deprecated Use FormControl instead. See https://primer.style/react/FormControl for more details. */
 const FormGroupLabel = styled.label<SxProp>`
   display: block;
   margin: 0 0 ${get('space.2')};

src/InputField/InputField.tsx

@@ -40,6 +40,7 @@ export interface InputFieldContext
   validationMessageId: string
 }
 
+/** @deprecated Use FormControl instead. See https://primer.style/react/FormControl for more details. */
 const InputField = <T extends Record<string, FormValidationStatus>>({
   children,
   disabled,

src/deprecated/index.ts

@@ -0,0 +1,31 @@
+/** This is the place where we keep components that are deprecated.
+ *  We don't recommend using it in production.
+ *  If you already use them, please move to the suggested alternative components
+ *
+ *  But, they are published on npm and you can import them.
+ *  example: import {FormGroup} from '@primer/react/deprecated
+ */
+
+export {default as BorderBox} from '../BorderBox'
+export type {BorderBoxProps} from '../BorderBox'
+export {default as Flex} from '../Flex'
+export type {FlexProps} from '../Flex'
+export {default as Grid} from '../Grid'
+export type {GridProps} from '../Grid'
+export {default as Position, Absolute, Fixed, Relative, Sticky} from '../Position'
+export type {PositionProps, AbsoluteProps, FixedProps, RelativeProps, StickyProps} from '../Position'
+export {default as Dialog} from '../Dialog'
+export type {DialogProps, DialogHeaderProps} from '../Dialog'
+export {ConfirmationDialog} from '../Dialog/ConfirmationDialog'
+export {default as Dropdown} from '../Dropdown'
+export type {
+  DropdownProps,
+  DropdownCaretProps,
+  DropdownButtonProps,
+  DropdownItemProps,
+  DropdownMenuProps
+} from '../Dropdown'
+export {default as FormGroup} from '../FormGroup'
+export type {FormGroupProps, FormGroupLabelProps} from '../FormGroup'
+export {default as InputField} from '../InputField'
+export {default as SelectMenu} from '../SelectMenu'

src/index.ts

@@ -103,7 +103,6 @@ export {default as Header} from './Header'
 export type {HeaderProps, HeaderItemProps, HeaderLinkProps} from './Header'
 export {default as Heading} from './Heading'
 export type {HeadingProps} from './Heading'
-export {default as InputField} from './InputField'
 export {default as LabelGroup} from './LabelGroup'
 export type {LabelGroupProps} from './LabelGroup'
 export {default as Label} from './Label'