Make FormControl externally extensible (via HOC)

.changeset/forty-days-sleep.md

@@ -0,0 +1,7 @@
+---
+"@primer/react": patch
+---
+
+Allow consumers to mark components as compatible with `FormControl` autowiring by wrapping them in `FormControl.autowirable`
+
+<!-- Changed components: FormControl -->

src/Autocomplete/Autocomplete.tsx

@@ -1,10 +1,10 @@
 import React, {useCallback, useReducer, useRef} from 'react'
-import {ComponentProps} from '../utils/types'
 import {AutocompleteContext} from './AutocompleteContext'
 import AutocompleteInput from './AutocompleteInput'
 import AutocompleteMenu from './AutocompleteMenu'
 import AutocompleteOverlay from './AutocompleteOverlay'
 import {useId} from '../hooks/useId'
+import FormControl from '../FormControl/FormControl'
 
 type Action =
  | {type: 'showMenu' | 'isMenuDirectlyActivated'; payload: boolean}
@@ -45,7 +45,10 @@ const reducer = (state: State, action: Action) => {
  }
 }
 
-const Autocomplete: React.FC<React.PropsWithChildren<{id?: string}>> = ({children, id: idProp}) => {
+type AutocompleteProps = React.PropsWithChildren<{id?: string}>
+
+// FIXME: Does not forward all of the required FormControl props
+const Autocomplete = FormControl.autowirable(({children, id: idProp}: AutocompleteProps) => {
  const activeDescendantRef = useRef<HTMLElement>(null)
  const scrollContainerRef = useRef<HTMLDivElement>(null)
  const inputRef = useRef<HTMLInputElement>(null)
@@ -90,9 +93,8 @@ const Autocomplete: React.FC<React.PropsWithChildren<{id?: string}>> = ({childre
  {children}
  </AutocompleteContext.Provider>
  )
-}
+})
 
-export type AutocompleteProps = ComponentProps<typeof Autocomplete>
 export type {AutocompleteInputProps} from './AutocompleteInput'
 export type {AutocompleteMenuProps} from './AutocompleteMenu'
 export type {AutocompleteOverlayProps} from './AutocompleteOverlay'

src/Checkbox/Checkbox.tsx

@@ -1,13 +1,15 @@
 import styled from 'styled-components'
 import {useProvidedRefOrCreate} from '../hooks'
-import React, {ChangeEventHandler, InputHTMLAttributes, ReactElement, useContext} from 'react'
+import React, {ChangeEventHandler, InputHTMLAttributes, useContext} from 'react'
 import sx, {SxProp} from '../sx'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 import {FormValidationStatus} from '../utils/types/FormValidationStatus'
 import {CheckboxGroupContext} from '../CheckboxGroup/CheckboxGroupContext'
 import getGlobalFocusStyles from '../internal/utils/getGlobalFocusStyles'
 import {get} from '../constants'
 import {sharedCheckboxAndRadioStyles} from '../internal/utils/sharedCheckboxAndRadioStyles'
+// direct import to avoid circular dependency
+import {autowirable} from '../FormControl/autowirable'
 
 export type CheckboxProps = {
  /**
@@ -131,42 +133,41 @@ const StyledCheckbox = styled.input`
 /**
  * An accessible, native checkbox component
  */
-const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
- (
- {checked, indeterminate, disabled, onChange, sx: sxProp, required, validationStatus, value, ...rest}: CheckboxProps,
- ref,
- ): ReactElement => {
- const checkboxRef = useProvidedRefOrCreate(ref as React.RefObject<HTMLInputElement>)
- const checkboxGroupContext = useContext(CheckboxGroupContext)
- const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
- checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
- onChange && onChange(e)
- }
-
- useLayoutEffect(() => {
- if (checkboxRef.current) {
- checkboxRef.current.indeterminate = indeterminate || false
+const Checkbox = autowirable(
+ React.forwardRef<HTMLInputElement, CheckboxProps>(
+ ({checked, indeterminate, disabled, onChange, sx: sxProp, required, validationStatus, value, ...rest}, ref) => {
+ const checkboxRef = useProvidedRefOrCreate(ref as React.RefObject<HTMLInputElement>)
+ const checkboxGroupContext = useContext(CheckboxGroupContext)
+ const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
+ checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
+ onChange && onChange(e)
  }
- }, [indeterminate, checked, checkboxRef])
-
- return (
- <StyledCheckbox
- type="checkbox"
- disabled={disabled}
- ref={ref || checkboxRef}
- checked={indeterminate ? false : checked}
- aria-checked={indeterminate ? 'mixed' : checked ? 'true' : 'false'}
- sx={sxProp}
- required={required}
- aria-required={required ? 'true' : 'false'}
- aria-invalid={validationStatus === 'error' ? 'true' : 'false'}
- onChange={handleOnChange}
- value={value}
- name={value}
- {...rest}
- />
- )
- },
+
+ useLayoutEffect(() => {
+ if (checkboxRef.current) {
+ checkboxRef.current.indeterminate = indeterminate || false
+ }
+ }, [indeterminate, checked, checkboxRef])
+
+ return (
+ <StyledCheckbox
+ type="checkbox"
+ disabled={disabled}
+ ref={ref || checkboxRef}
+ checked={indeterminate ? false : checked}
+ aria-checked={indeterminate ? 'mixed' : checked ? 'true' : 'false'}
+ sx={sxProp}
+ required={required}
+ aria-required={required ? 'true' : 'false'}
+ aria-invalid={validationStatus === 'error' ? 'true' : 'false'}
+ onChange={handleOnChange}
+ value={value}
+ name={value}
+ {...rest}
+ />
+ )
+ },
+ ),
 )
 
 Checkbox.displayName = 'Checkbox'

src/FormControl/FormControl.tsx

@@ -1,23 +1,18 @@
 import React, {useContext} from 'react'
-import Autocomplete from '../Autocomplete'
 import Box from '../Box'
 import Checkbox from '../Checkbox'
 import Radio from '../Radio'
-import Select from '../Select'
-import TextInput from '../TextInput'
-import TextInputWithTokens from '../TextInputWithTokens'
-import Textarea from '../Textarea'
-import {CheckboxOrRadioGroupContext} from '../internal/components/CheckboxOrRadioGroup'
-import ValidationAnimationContainer from '../internal/components/ValidationAnimationContainer'
 import {get} from '../constants'
-import InlineAutocomplete from '../drafts/InlineAutocomplete'
 import {useSlots} from '../hooks/useSlots'
+import {CheckboxOrRadioGroupContext} from '../internal/components/CheckboxOrRadioGroup'
+import ValidationAnimationContainer from '../internal/components/ValidationAnimationContainer'
 import {SxProp} from '../sx'
 import {useSSRSafeId} from '../utils/ssr'
 import FormControlCaption from './_FormControlCaption'
 import FormControlLabel from './_FormControlLabel'
 import FormControlLeadingVisual from './_FormControlLeadingVisual'
 import FormControlValidation from './_FormControlValidation'
+import {autowirable, isValidAutowirableElement} from './autowirable'
 
 export type FormControlProps = {
  children?: React.ReactNode
@@ -55,43 +50,33 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
  leadingVisual: FormControlLeadingVisual,
  validation: FormControlValidation,
  })
- const expectedInputComponents = [
- Autocomplete,
- Checkbox,
- Radio,
- Select,
- TextInput,
- TextInputWithTokens,
- Textarea,
- InlineAutocomplete,
- ]
  const choiceGroupContext = useContext(CheckboxOrRadioGroupContext)
  const disabled = choiceGroupContext.disabled || disabledProp
  const id = useSSRSafeId(idProp)
  const validationMessageId = slots.validation ? `${id}-validationMessage` : undefined
  const captionId = slots.caption ? `${id}-caption` : undefined
  const validationStatus = slots.validation?.props.variant
- const InputComponent = childrenWithoutSlots.find(child =>
- expectedInputComponents.some(inputComponent => React.isValidElement(child) && child.type === inputComponent),
- )
- const inputProps = React.isValidElement(InputComponent) && InputComponent.props
+ const InputComponent = childrenWithoutSlots.find(isValidAutowirableElement)
+
+ // we don't make the mark symbol public, so TS thinks it's impossible that the types could overlap
  const isChoiceInput =
-React.isValidElement(InputComponent) && (InputComponent.type === Checkbox || InputComponent.type === Radio)
+ InputComponent && ((InputComponent.type as unknown) === Checkbox || (InputComponent.type as unknown) === Radio)
 
  if (InputComponent) {
- if (inputProps?.id) {
+ const inputProps = InputComponent.props
+ if (inputProps.id) {
  // eslint-disable-next-line no-console
  console.warn(
  `instead of passing the 'id' prop directly to the input component, it should be passed to the parent component, <FormControl>`,
  )
  }
- if (inputProps?.disabled) {
+ if (inputProps.disabled) {
  // eslint-disable-next-line no-console
  console.warn(
  `instead of passing the 'disabled' prop directly to the input component, it should be passed to the parent component, <FormControl>`,
  )
  }
- if (inputProps?.required) {
+ if (inputProps.required) {
  // eslint-disable-next-line no-console
  console.warn(
  `instead of passing the 'required' prop directly to the input component, it should be passed to the parent component, <FormControl>`,
@@ -197,25 +182,16 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
  sx={{...(isLabelHidden ? {'> *:not(label) + *': {marginTop: 1}} : {'> * + *': {marginTop: 1}}), ...sx}}
  >
  {slots.label}
- {React.isValidElement(InputComponent) &&
- React.cloneElement(
- InputComponent,
- Object.assign(
- {
- id,
- required,
- disabled,
- validationStatus,
- ['aria-describedby']: [validationMessageId, captionId].filter(Boolean).join(' '),
- },
- InputComponent.props,
- ),
- )}
- {childrenWithoutSlots.filter(
- child =>
- React.isValidElement(child) &&
- !expectedInputComponents.some(inputComponent => child.type === inputComponent),
- )}
+ {InputComponent &&
+ React.cloneElement(InputComponent, {
+ id,
+ required,
+ disabled,
+ validationStatus,
+ ['aria-describedby']: [validationMessageId, captionId].filter(Boolean).join(' '),
+ ...InputComponent.props,
+ })}
+ {childrenWithoutSlots.filter(child => child !== InputComponent)}
  {slots.validation ? (
  <ValidationAnimationContainer show>{slots.validation}</ValidationAnimationContainer>
  ) : null}
@@ -232,4 +208,5 @@ export default Object.assign(FormControl, {
  Label: FormControlLabel,
  LeadingVisual: FormControlLeadingVisual,
  Validation: FormControlValidation,
+ autowirable,
 })

src/FormControl/autowirable.ts

@@ -0,0 +1,41 @@
+import {ComponentType, FC, ReactElement, isValidElement} from 'react'
+import {FormValidationStatus} from '../utils/types/FormValidationStatus'
+
+/**
+ * Presence of this symbol on a component indicates that it supports `FormControl``s auto-wiring features.
+ * By not exporting this symbol we force consumers to use the HOC wrapper function, ensuring that the prop types align.
+ */
+const supportsAutowiring = Symbol('FormControl.supportsAutowiring')
+
+/**
+ * When a supported component is used as a child of `FormControl`, it will be cloned and these props will be
+ * overidden to auto-wire accessibility features. These props should be forwarded to the underlying form control,
+ * typically a Primer component.
+ */
+export interface FormControlForwardedProps {
+ id?: string
+ required?: boolean
+ disabled?: boolean
+ ['aria-describedby']?: string
+ validationStatus?: FormValidationStatus
+}
+
+type AutowirableComponent = FC<FormControlForwardedProps> & {
+ [supportsAutowiring]: unknown
+}
+
+type AutowirableElement = ReactElement<FormControlForwardedProps, AutowirableComponent>
+
+/**
+ * Mark a component to indicate that it supports `FormControl` autowiring by forwarding the props in
+ * `FormControlAutowireComponentProps` to an underlying form element or component. This is useful when
+ * wrapping/extending Primer form controls to make them easier to use.
+ */
+// use explicit return type to hide the `supportsAutoWiring` symbol from the public API
+export function autowirable<P extends FormControlForwardedProps>(component: ComponentType<P>): ComponentType<P> {
+ return Object.assign(component, {[supportsAutowiring]: true})
+}
+
+export function isValidAutowirableElement(object: Parameters<typeof isValidElement>[0]): object is AutowirableElement {
+ return isValidElement(object) && Object.getOwnPropertySymbols(object.type).includes(supportsAutowiring)
+}

src/FormControl/index.ts

@@ -1 +1,2 @@
 export {default} from './FormControl'
+export type {FormControlForwardedProps} from './autowirable'

src/Radio/Radio.tsx

@@ -6,6 +6,8 @@ import {RadioGroupContext} from '../RadioGroup/RadioGroup'
 import getGlobalFocusStyles from '../internal/utils/getGlobalFocusStyles'
 import {get} from '../constants'
 import {sharedCheckboxAndRadioStyles} from '../internal/utils/sharedCheckboxAndRadioStyles'
+// direct import to avoid circular dependency
+import {autowirable} from '../FormControl/autowirable'
 
 export type RadioProps = {
  /**
@@ -68,43 +70,45 @@ const StyledRadio = styled.input`
 /**
  * An accessible, native radio component for selecting one option from a list.
  */
-const Radio = React.forwardRef<HTMLInputElement, RadioProps>(
- (
- {checked, disabled, name: nameProp, onChange, sx: sxProp, required, validationStatus, value, ...rest}: RadioProps,
- ref,
- ): ReactElement => {
- const radioGroupContext = useContext(RadioGroupContext)
- const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
- radioGroupContext?.onChange && radioGroupContext.onChange(e)
- onChange && onChange(e)
- }
- const name = nameProp || radioGroupContext?.name
+const Radio = autowirable(
+ React.forwardRef<HTMLInputElement, RadioProps>(
+ (
+ {checked, disabled, name: nameProp, onChange, sx: sxProp, required, validationStatus, value, ...rest}: RadioProps,
+ ref,
+ ): ReactElement => {
+ const radioGroupContext = useContext(RadioGroupContext)
+ const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
+ radioGroupContext?.onChange && radioGroupContext.onChange(e)
+ onChange && onChange(e)
+ }
+ const name = nameProp || radioGroupContext?.name
 
- if (!name) {
- // eslint-disable-next-line no-console
- console.warn(
- 'A radio input must have a `name` attribute. Pass `name` as a prop directly to each Radio, or nest them in a `RadioGroup` component with a `name` prop',
- )
- }
+if (!name) {
+// eslint-disable-next-line no-console
+console.warn(
+'A radio input must have a `name` attribute. Pass `name` as a prop directly to each Radio, or nest them in a `RadioGroup` component with a `name` prop',
+)
+}
 
- return (
- <StyledRadio
- type="radio"
- value={value}
- name={name}
- ref={ref}
- disabled={disabled}
- checked={checked}
- aria-checked={checked ? 'true' : 'false'}
- required={required}
- aria-required={required ? 'true' : 'false'}
- aria-invalid={validationStatus === 'error' ? 'true' : 'false'}
- sx={sxProp}
- onChange={handleOnChange}
- {...rest}
- />
- )
- },
+ return (
+ <StyledRadio
+ type="radio"
+ value={value}
+ name={name}
+ ref={ref}
+ disabled={disabled}
+ checked={checked}
+ aria-checked={checked ? 'true' : 'false'}
+ required={required}
+ aria-required={required ? 'true' : 'false'}
+ aria-invalid={validationStatus === 'error' ? 'true' : 'false'}
+ sx={sxProp}
+ onChange={handleOnChange}
+ {...rest}
+ />
+ )
+ },
+ ),
 )
 
 Radio.displayName = 'Radio'