Merge branch 'main' into fix-textinput-types

Author: colebemis

.changeset/spotty-eagles-help.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Instead of rendering unexpected FormControl children before the rest of the content, we render them in the same spot we'd normally render a Primer input component

docs/content/FormControl.mdx

@@ -91,6 +91,89 @@ const DifferentInputs = () => {
 render(DifferentInputs)
 ```
 
+### With a custom input
+
+<Note variant="warning">
+
+When rendering an input other than a form component from Primer, you must manually pass the attributes that make the form control accessible:
+
+- The input should have an ID
+- `FormControl.Label` should be associated with the text input by using `htmlFor`
+- If there is a caption, the input should be associated with the caption by passing the message's ID to `aria-describedby`
+- If there is a validation message, the input should be associated with the message by passing the message's ID to `aria-describedby`
+- If there is both a caption and a validation message, the input should be associated with the message by passing the both the validation message's ID and the caption's ID to `aria-describedby`. Example: `aria-describedby="caption-id validation-id"`
+- If the input's value is invalid, `aria-invalid={true}` should be passed to the input.
+- If the input is disabled, `disabled` should be passed.
+- If the input is required, `required` should be passed.
+
+When rendering a custom checkbox or radio component, you must also pass `layout="horizontal"` to the `FormControl` component.
+
+</Note>
+
+```javascript live noinline
+const CustomTextInput = props => <input type="text" {...props} />
+const CustomCheckboxInput = props => <input type="checkbox" {...props} />
+const FormControlWithCustomInput = () => {
+  const [value, setValue] = React.useState('mona lisa')
+  const [validationResult, setValidationResult] = React.useState()
+  const doesValueContainSpaces = inputValue => /\s/g.test(inputValue)
+  const handleInputChange = e => {
+    setValue(e.currentTarget.value)
+  }
+
+  React.useEffect(() => {
+    if (doesValueContainSpaces(value)) {
+      setValidationResult('noSpaces')
+    } else if (value) {
+      setValidationResult('validName')
+    }
+  }, [value])
+
+  return (
+    <Box display="grid" gridGap={3}>
+      <FormControl>
+        <FormControl.Label htmlFor="custom-input">GitHub handle</FormControl.Label>
+        <CustomTextInput
+          id="custom-input"
+          aria-describedby="custom-input-caption custom-input-validation"
+          aria-invalid={validationResult === 'noSpaces'}
+          onChange={handleInputChange}
+        />
+        {validationResult === 'noSpaces' && (
+          <FormControl.Validation id="custom-input-validation" variant="error">
+            GitHub handles cannot contain spaces
+          </FormControl.Validation>
+        )}
+        {validationResult === 'validName' && (
+          <FormControl.Validation id="custom-input-validation" variant="success">
+            Valid name
+          </FormControl.Validation>
+        )}
+        <FormControl.Caption id="custom-input-caption">
+          With or without "@". For example "monalisa" or "@monalisa"
+        </FormControl.Caption>
+      </FormControl>
+
+      <CheckboxGroup>
+        <CheckboxGroup.Label>Checkboxes</CheckboxGroup.Label>
+        <FormControl layout="horizontal">
+          <CustomCheckboxInput id="custom-checkbox-one" value="checkOne" />
+          <FormControl.Label htmlFor="custom-checkbox-one">Checkbox one</FormControl.Label>
+          <FormControl.Caption id="custom-checkbox-one-caption">Hint text for checkbox one</FormControl.Caption>
+        </FormControl>
+        <FormControl layout="horizontal">
+          <CustomCheckboxInput id="custom-checkbox-two" value="checkTwo" />
+          <FormControl.Label htmlFor="custom-checkbox-two">Checkbox two</FormControl.Label>
+          <FormControl.Caption id="custom-checkbox-two-caption">Hint text for checkbox two</FormControl.Caption>
+        </FormControl>
+      </CheckboxGroup>
+    </Box>
+  )
+}
+
+render(FormControlWithCustomInput)
+```
+
 ### With checkbox and radio inputs
 
 ```jsx live

docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js

@@ -12,11 +12,14 @@ const ReactRouterLink = ({to, ...props}) => {
   return <a href={to} {...props} />
 }
 
+// Exclude octicons-react's default export because it's deprecated
+const {default: _, ...octiconComponents} = octicons
+
 export default function resolveScope(metastring) {
   return {
     ...doctocatComponents,
     ...primerComponents,
-    ...octicons,
+    ...octiconComponents,
     ...(metastring.includes('drafts') ? drafts : {}),
     ...(metastring.includes('deprecated') ? deprecated : {}),
     ReactRouterLink,

src/FormControl/FormControl.tsx

@@ -24,6 +24,11 @@ export type FormControlProps = {
    * If true, the user must specify a value for the input before the owning form can be submitted
    */
   required?: boolean
+  /**
+   * The direction the content flows.
+   * Vertical layout is used by default, and horizontal layout is used for checkbox and radio inputs.
+   */
+  layout?: 'horizontal' | 'vertical'
 } & SxProp
 
 export interface FormControlContext extends Pick<FormControlProps, 'disabled' | 'id' | 'required'> {
@@ -32,7 +37,7 @@ export interface FormControlContext extends Pick<FormControlProps, 'disabled' |
 }
 
 const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
-  ({children, disabled: disabledProp, id: idProp, required, sx}, ref) => {
+  ({children, disabled: disabledProp, layout, id: idProp, required, sx}, ref) => {
     const expectedInputComponents = [Autocomplete, Checkbox, Radio, Select, TextInput, TextInputWithTokens, Textarea]
     const choiceGroupContext = useContext(CheckboxOrRadioGroupContext)
     const disabled = choiceGroupContext?.disabled || disabledProp
@@ -56,20 +61,7 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
     const isChoiceInput =
       React.isValidElement(InputComponent) && (InputComponent.type === Checkbox || InputComponent.type === Radio)
 
-    if (!InputComponent) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `To correctly render this field with the correct ARIA attributes passed to the input, please pass one of the component from @primer/react as a direct child of the FormControl component: ${expectedInputComponents.reduce(
-          (acc, componentName) => {
-            acc += `\n- ${componentName.displayName}`
-
-            return acc
-          },
-          ''
-        )}`,
-        'If you are using a custom input component, please be sure to follow WCAG guidelines to make your form control accessible.'
-      )
-    } else {
+    if (InputComponent) {
       if (inputProps?.id) {
         // eslint-disable-next-line no-console
         console.warn(
@@ -135,7 +127,7 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
         {slots => {
           const isLabelHidden = React.isValidElement(slots.Label) && slots.Label.props.visuallyHidden
 
-          return isChoiceInput ? (
+          return isChoiceInput || layout === 'horizontal' ? (
             <Box ref={ref} display="flex" alignItems={slots.LeadingVisual ? 'center' : undefined} sx={sx}>
               <Box sx={{'> input': {marginLeft: 0, marginRight: 0}}}>
                 {React.isValidElement(InputComponent) &&
@@ -183,13 +175,8 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
               display="flex"
               flexDirection="column"
               width="100%"
-              sx={{...(isLabelHidden ? {'> *:not(label) + *': {marginTop: 2}} : {'> * + *': {marginTop: 2}}), ...sx}}
+              sx={{...(isLabelHidden ? {'> *:not(label) + *': {marginTop: 1}} : {'> * + *': {marginTop: 1}}), ...sx}}
             >
-              {React.Children.toArray(children).filter(
-                child =>
-                  React.isValidElement(child) &&
-                  !expectedInputComponents.some(inputComponent => child.type === inputComponent)
-              )}
               {slots.Label}
               {React.isValidElement(InputComponent) &&
                 React.cloneElement(InputComponent, {
@@ -199,6 +186,11 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
                   validationStatus,
                   ['aria-describedby']: [validationMessageId, captionId].filter(Boolean).join(' ')
                 })}
+              {React.Children.toArray(children).filter(
+                child =>
+                  React.isValidElement(child) &&
+                  !expectedInputComponents.some(inputComponent => child.type === inputComponent)
+              )}
               {validationChild && <ValidationAnimationContainer show>{slots.Validation}</ValidationAnimationContainer>}
               {slots.Caption}
             </Box>
@@ -209,6 +201,10 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
   }
 )
 
+FormControl.defaultProps = {
+  layout: 'vertical'
+}
+
 export default Object.assign(FormControl, {
   Caption: FormControlCaption,
   Label: FormControlLabel,

src/FormControl/_FormControlCaption.tsx

@@ -4,10 +4,10 @@ import InputCaption from '../_InputCaption'
 import {FormControlContext} from './FormControl'
 import {Slot} from './slots'
 
-const FormControlCaption: React.FC<SxProp> = ({children, sx}) => (
+const FormControlCaption: React.FC<{id?: string} & SxProp> = ({children, sx, id}) => (
   <Slot name="Caption">
     {({captionId, disabled}: FormControlContext) => (
-      <InputCaption id={captionId} disabled={disabled} sx={sx}>
+      <InputCaption id={id || captionId} disabled={disabled} sx={sx}>
         {children}
       </InputCaption>
     )}

src/FormControl/_FormControlLabel.tsx

@@ -11,10 +11,16 @@ export type Props = {
   visuallyHidden?: boolean
 } & SxProp
 
-const FormControlLabel: React.FC<Props> = ({children, visuallyHidden, sx}) => (
+const FormControlLabel: React.FC<{htmlFor?: string} & Props> = ({children, htmlFor, visuallyHidden, sx}) => (
   <Slot name="Label">
     {({disabled, id, required}: FormControlContext) => (
-      <InputLabel htmlFor={id} visuallyHidden={visuallyHidden} required={required} disabled={disabled} sx={sx}>
+      <InputLabel
+        htmlFor={htmlFor || id}
+        visuallyHidden={visuallyHidden}
+        required={required}
+        disabled={disabled}
+        sx={sx}
+      >
         {children}
       </InputLabel>
     )}

src/FormControl/_FormControlValidation.tsx

@@ -7,12 +7,13 @@ import {Slot} from './slots'
 
 export type FormControlValidationProps = {
   variant: FormValidationStatus
+  id?: string
 } & SxProp
 
-const FormControlValidation: React.FC<FormControlValidationProps> = ({children, variant, sx}) => (
+const FormControlValidation: React.FC<FormControlValidationProps> = ({children, variant, sx, id}) => (
   <Slot name="Validation">
     {({validationMessageId}: FormControlContext) => (
-      <InputValidation validationStatus={variant} id={validationMessageId} sx={sx}>
+      <InputValidation validationStatus={variant} id={id || validationMessageId} sx={sx}>
         {children}
       </InputValidation>
     )}

src/_CheckboxOrRadioGroup/CheckboxOrRadioGroup.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import {Box, Checkbox, FormControl, Radio, useSSRSafeId} from '..'
+import {Box, useSSRSafeId} from '..'
 import ValidationAnimationContainer from '../_ValidationAnimationContainer'
 import CheckboxOrRadioGroupCaption from './_CheckboxOrRadioGroupCaption'
 import CheckboxOrRadioGroupLabel from './_CheckboxOrRadioGroupLabel'
@@ -56,7 +56,6 @@ const CheckboxOrRadioGroup: React.FC<CheckboxOrRadioGroupProps> = ({
   required,
   sx
 }) => {
-  const expectedInputComponents = [Checkbox, Radio]
   const labelChild = React.Children.toArray(children).find(
     child => React.isValidElement(child) && child.type === CheckboxOrRadioGroupLabel
   )
@@ -69,25 +68,6 @@ const CheckboxOrRadioGroup: React.FC<CheckboxOrRadioGroupProps> = ({
   const id = useSSRSafeId(idProp)
   const validationMessageId = validationChild && `${id}-validationMessage`
   const captionId = captionChild && `${id}-caption`
-  const checkIfOnlyContainsChoiceInputs = () => {
-    const formControlComponentChildren = React.Children.toArray(children)
-      .filter(child => React.isValidElement(child) && child.type === FormControl)
-      .map(formControlComponent =>
-        React.isValidElement(formControlComponent) ? formControlComponent.props.children : []
-      )
-      .flat()
-
-    return Boolean(
-      React.Children.toArray(formControlComponentChildren).find(child =>
-        expectedInputComponents.some(inputComponent => React.isValidElement(child) && child.type === inputComponent)
-      )
-    )
-  }
-
-  if (!checkIfOnlyContainsChoiceInputs()) {
-    // eslint-disable-next-line no-console
-    console.warn('Only `Checkbox` and `Radio` form controls should be used in a `CheckboxOrRadioGroup`.')
-  }
 
   if (!labelChild && !ariaLabelledby) {
     // eslint-disable-next-line no-console

src/__tests__/FormControl.test.tsx

@@ -257,31 +257,6 @@ describe('FormControl', () => {
     })
 
     describe('warnings', () => {
-      it('should warn users if they do not pass an input', async () => {
-        render(
-          <SSRProvider>
-            <FormControl>
-              <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
-              <FormControl.Caption>{CAPTION_TEXT}</FormControl.Caption>
-            </FormControl>
-          </SSRProvider>
-        )
-
-        expect(mockWarningFn).toHaveBeenCalled()
-      })
-      it('should warn users if they try to render a choice (checkbox or radio) input', async () => {
-        render(
-          <SSRProvider>
-            <FormControl>
-              <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
-              <Checkbox />
-              <FormControl.Caption>{CAPTION_TEXT}</FormControl.Caption>
-            </FormControl>
-          </SSRProvider>
-        )
-
-        expect(mockWarningFn).toHaveBeenCalled()
-      })
       it('should log an error if a user does not pass a label', async () => {
         render(
           <SSRProvider>

src/stories/FormControl.stories.tsx

@@ -140,6 +140,23 @@ export const UsingRadioInput = (args: Args) => (
   </FormControl>
 )
 
+export const UsingCustomInput = (args: Args) => (
+  <FormControl {...args}>
+    <FormControl.Label htmlFor="custom-input">Name</FormControl.Label>
+    <input
+      type="text"
+      id="custom-input"
+      aria-describedby="custom-input-caption custom-input-validation"
+      disabled={args.disabled}
+      required={args.required}
+    />
+    <FormControl.Caption id="custom-input-caption">Your first name</FormControl.Caption>
+    <FormControl.Validation variant="success" id="custom-input-validation">
+      Not a valid name
+    </FormControl.Validation>
+  </FormControl>
+)
+
 export const WithLeadingVisual = (args: Args) => (
   <FormControl {...args}>
     <FormControl.Label>Selectable choice</FormControl.Label>