Checkbox: replace useLayoutEffect with ref callback for indeterminate

.changeset/checkbox-ref-callback.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+Checkbox: replace useLayoutEffect with ref callback for setting indeterminate state

packages/react/src/Checkbox/Checkbox.tsx

@@ -1,7 +1,6 @@
 import {clsx} from 'clsx'
-import {useProvidedRefOrCreate} from '../hooks'
-import React, {useContext, useEffect, type ChangeEventHandler, type InputHTMLAttributes, type ReactElement} from 'react'
-import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
+import {useMergedRefs} from '../hooks'
+import React, {useContext, type ChangeEventHandler, type InputHTMLAttributes, type ReactElement} from 'react'
 import type {FormValidationStatus} from '../utils/types/FormValidationStatus'
 import {CheckboxGroupContext} from '../CheckboxGroup/CheckboxGroupContext'
 import classes from './Checkbox.module.css'
@@ -45,46 +44,48 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     ref,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
-    const checkboxRef = useProvidedRefOrCreate(ref as React.RefObject<HTMLInputElement>)
+    const setIndeterminate = React.useCallback(
+      (node: HTMLInputElement | null) => {
+        if (node) {
+          node.indeterminate = indeterminate || false
+        }
+      },
+      // `checked` is intentionally included even though it is not used inside
+      // the callback: browsers silently clear the `indeterminate` property
+      // whenever the checked state changes, so the callback must re-run to
+      // restore it. The exhaustive-deps rule flags this as an unnecessary
+      // dependency (because `checked` isn't referenced in the body), hence the
+      // suppression below.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [indeterminate, checked],
+    )
+    const mergedRef = useMergedRefs(ref, setIndeterminate)
+
     const checkboxGroupContext = useContext(CheckboxGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
       onChange && onChange(e)
     }
+
+    // aria-checked must reflect three states: mixed (indeterminate), true, or false.
+    const ariaChecked = indeterminate ? ('mixed' as const) : checked ? ('true' as const) : ('false' as const)
+
     const inputProps = {
       type: 'checkbox',
       disabled,
-      ref: checkboxRef,
+      ref: mergedRef,
       checked: indeterminate ? false : checked,
       defaultChecked,
       required,
       ['aria-required']: required ? ('true' as const) : ('false' as const),
       ['aria-invalid']: validationStatus === 'error' ? ('true' as const) : ('false' as const),
+      ['aria-checked']: ariaChecked,
       onChange: handleOnChange,
       value,
       name: value,
       ...rest,
     }
 
-    useLayoutEffect(() => {
-      if (checkboxRef.current) {
-        checkboxRef.current.indeterminate = indeterminate || false
-      }
-    }, [indeterminate, checked, checkboxRef])
-
-    useEffect(() => {
-      const {current: checkbox} = checkboxRef
-      if (!checkbox) {
-        return
-      }
-
-      if (indeterminate) {
-        checkbox.setAttribute('aria-checked', 'mixed')
-      } else {
-        checkbox.setAttribute('aria-checked', checkbox.checked ? 'true' : 'false')
-      }
-    })
-    // @ts-expect-error inputProp needs a non nullable ref
     return <input {...inputProps} className={clsx(className, sharedClasses.Input, classes.Checkbox)} />
   },
 )