Deprecate components replaced by FormControl (#1888)

mperrotti · web-flow · commit f94dcd33ffa2 · 2022-03-01T08:14:57.000-05:00
* moves InputField to deprecated package

* adds jsdoc comments for deprecation

* adds changeset

* fixes bad autoformatting in changeset

* fixes import path in test file

* addresses PR feedback

* fixes FormGroup import in test

* addresses PR feedback

* moves tests to depreacted directory

* removes docs header image

* fixes bad formatting in changelog markdown
diff --git a/.changeset/olive-bears-act.md b/.changeset/olive-bears-act.md
@@ -0,0 +1,109 @@
+---
+'@primer/react': major
+---
+
+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
+```
+
+Codemods:
+
+- InputField codemod: https://github.com/primer/react-migrate/blob/main/src/use-deprecated-inputfield.js
+- ChoiceInputField https://github.com/primer/react-migrate/blob/main/src/use-deprecated-choiceinputfield.js
+- FormGroup codemod: https://github.com/primer/react-migrate/blob/main/src/use-deprecated-formgroup.js
+
+</td>
+</tr>
+</table>
diff --git a/docs/content/deprecated/FormGroup.md b/docs/content/deprecated/FormGroup.md
@@ -12,7 +12,7 @@ Use [FormControl](/FormControl) instead.
 
 ## Default example
 
-```jsx live
+```jsx live deprecated
 <>
   <FormGroup>
     <FormGroup.Label htmlFor="example-text">Example text</FormGroup.Label>
diff --git a/docs/content/deprecated/InputField.mdx b/docs/content/deprecated/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()
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -164,9 +164,11 @@
     - title: Flex
       url: /deprecated/Flex
     - title: FormGroup
-      url: /FormGroup
+      url: /deprecated/FormGroup
     - title: Grid
       url: /deprecated/Grid
+    - title: InputField
+      url: /deprecated/InputField
     - title: Position
       url: /deprecated/Position
     - title: SelectMenu
diff --git a/src/ChoiceInputField.tsx b/src/ChoiceInputField.tsx
@@ -1,11 +1,11 @@
 import React from 'react'
 import {Box, Checkbox, Radio, useSSRSafeId} from '.'
 import {get} from './constants'
-import {Slots} from './InputField/slots'
+import {Slots} from './deprecated/InputField/slots'
 import ChoiceInputLeadingVisual from './_ChoiceInputLeadingVisual'
-import InputField, {Props as InputFieldProps} from './InputField/InputField'
+import InputField, {Props as InputFieldProps} from './deprecated/InputField/InputField'
 import {FormValidationStatus} from './utils/types/FormValidationStatus'
-import InputFieldCaption from './InputField/_InputFieldCaption'
+import InputFieldCaption from './deprecated/InputField/_InputFieldCaption'
 
 export interface Props extends Pick<InputFieldProps, 'disabled' | 'id'> {
   /**
diff --git a/src/_ChoiceInputLeadingVisual.tsx b/src/_ChoiceInputLeadingVisual.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import {Slot} from './InputField/slots'
+import {Slot} from './deprecated/InputField/slots'
 
 const ChoiceInputLeadingVisual: React.FC = ({children}) => <Slot name="LeadingVisual">{children}</Slot>
 
diff --git a/src/__tests__/FormGroup.types.test.tsx b/src/__tests__/FormGroup.types.test.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import FormGroup from '../FormGroup'
+import FormGroup from '../deprecated/FormGroup'
 
 export function shouldAcceptCallWithNoProps() {
   return <FormGroup />
diff --git a/src/__tests__/deprecated/FormGroup.test.tsx b/src/__tests__/deprecated/FormGroup.test.tsx
@@ -1,6 +1,6 @@
 import React from 'react'
-import {FormGroup} from '..'
-import {behavesAsComponent, checkExports} from '../utils/testing'
+import FormGroup from '../../deprecated/FormGroup'
+import {behavesAsComponent, checkExports} from '../../utils/testing'
 import {render as HTMLRender, cleanup} from '@testing-library/react'
 import {axe, toHaveNoViolations} from 'jest-axe'
 import 'babel-polyfill'
@@ -9,7 +9,7 @@ expect.extend(toHaveNoViolations)
 describe('FormGroup', () => {
   behavesAsComponent({Component: FormGroup})
 
-  checkExports('FormGroup', {
+  checkExports('deprecated/FormGroup', {
     default: FormGroup
   })
 
diff --git a/src/__tests__/deprecated/InputField.test.tsx b/src/__tests__/deprecated/InputField.test.tsx
@@ -2,7 +2,8 @@ import React from 'react'
 import {render, cleanup} from '@testing-library/react'
 import {axe, toHaveNoViolations} from 'jest-axe'
 import 'babel-polyfill'
-import {Autocomplete, InputField, SSRProvider, TextInput, TextInputWithTokens} from '..'
+import {Autocomplete, SSRProvider, TextInput, TextInputWithTokens} from '../../'
+import InputField from '../../deprecated/InputField'
 expect.extend(toHaveNoViolations)
 
 const TEXTINPUTFIELD_LABEL_TEXT = 'Name'
diff --git a/src/__tests__/deprecated/__snapshots__/FormGroup.test.tsx.snap b/src/__tests__/deprecated/__snapshots__/FormGroup.test.tsx.snap
diff --git a/src/deprecated/FormGroup.tsx b/src/deprecated/FormGroup.tsx
@@ -1,14 +1,15 @@
 import styled from 'styled-components'
-import {get} from './constants'
-import sx, {SxProp} from './sx'
-import {ComponentProps} from './utils/types'
+import {get} from '../constants'
+import sx, {SxProp} from '../sx'
+import {ComponentProps} from '../utils/types'
 
 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')};
@@ -21,4 +22,5 @@ FormGroupLabel.displayName = 'FormGroup.Label'
 
 export type FormGroupProps = ComponentProps<typeof FormGroup>
 export type FormGroupLabelProps = ComponentProps<typeof FormGroupLabel>
+/** @deprecated Use FormControl instead. See https://primer.style/react/FormControl for more details. */
 export default Object.assign(FormGroup, {Label: FormGroupLabel})
diff --git a/src/deprecated/InputField/InputField.tsx b/src/deprecated/InputField/InputField.tsx
@@ -1,13 +1,13 @@
 import React from 'react'
-import {Autocomplete, Box, Select, TextInput, TextInputWithTokens, useSSRSafeId} from '..'
-import InputValidation from '../_InputValidation'
-import {ComponentProps} from '../utils/types'
-import {FormValidationStatus} from '../utils/types/FormValidationStatus'
+import {Autocomplete, Box, Select, TextInput, TextInputWithTokens, useSSRSafeId} from '../../'
+import InputValidation from '../../_InputValidation'
+import {ComponentProps} from '../../utils/types'
+import {FormValidationStatus} from '../../utils/types/FormValidationStatus'
 import InputFieldCaption from './_InputFieldCaption'
 import InputFieldLabel from './_InputFieldLabel'
 import InputFieldValidation from './_InputFieldValidation'
 import {Slots} from './slots'
-import ValidationAnimationContainer from '../_ValidationAnimationContainer'
+import ValidationAnimationContainer from '../../_ValidationAnimationContainer'
 export interface Props<T = Record<string, FormValidationStatus>> {
   children?: React.ReactNode
   /**
@@ -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,
diff --git a/src/deprecated/InputField/_InputFieldCaption.tsx b/src/deprecated/InputField/_InputFieldCaption.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import InputCaption from '../_InputCaption'
+import InputCaption from '../../_InputCaption'
 import {InputFieldContext} from './InputField'
 import {Slot} from './slots'
 
diff --git a/src/deprecated/InputField/_InputFieldLabel.tsx b/src/deprecated/InputField/_InputFieldLabel.tsx
@@ -1,5 +1,5 @@
 import React from 'react'
-import InputLabel from '../_InputLabel'
+import InputLabel from '../../_InputLabel'
 import {InputFieldContext} from './InputField'
 import {Slot} from './slots'
 
diff --git a/src/deprecated/InputField/_InputFieldValidation.tsx b/src/deprecated/InputField/_InputFieldValidation.tsx
diff --git a/src/deprecated/InputField/index.ts b/src/deprecated/InputField/index.ts
diff --git a/src/deprecated/InputField/slots.ts b/src/deprecated/InputField/slots.ts
@@ -1,3 +1,3 @@
-import createSlots from '../utils/create-slots'
+import createSlots from '../../utils/create-slots'
 
 export const {Slots, Slot} = createSlots(['Caption', 'Input', 'Label', 'LeadingVisual'])
diff --git a/src/deprecated/index.ts b/src/deprecated/index.ts
@@ -22,6 +22,9 @@ export type {
   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'
 export type {
   SelectMenuProps,
diff --git a/src/index.ts b/src/index.ts
@@ -79,13 +79,10 @@ export type {FilterListProps, FilterListItemProps} from './FilterList'
 export {default as Flash} from './Flash'
 export type {FlashProps} from './Flash'
 export {default as FormControl} from './FormControl'
-export {default as FormGroup} from './FormGroup'
-export type {FormGroupProps, FormGroupLabelProps} from './FormGroup'
 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'
