Checkbox: Add forward ref (BREAKING CHANGE)

docs/src/Checkbox.doc.js

@@ -74,6 +74,13 @@ a checkbox and its indeterminism are independent.`,
         name: 'onClick',
         type: `({ event: SyntheticInputEvent<HTMLInputElement>, checked: boolean }) => void`,
       },
+      {
+        name: 'ref',
+        type: "React.Ref<'div'>",
+        description:
+          'Forward the ref to the underlying Box component wrapping the input element',
+        href: 'refExample',
+      },
       {
         name: 'size',
         type: `"sm" | "md"`,
@@ -183,6 +190,53 @@ function CheckboxExample() {
   />
 );
 
+card(
+  <Example
+    id="refExample"
+    name="Example: ref"
+    description={`
+    A \`Checkbox\` with an anchor ref to a Flyout component
+  `}
+    defaultCode={`
+function CheckboxFlyoutExample() {
+  const [open, setOpen] = React.useState(false);
+  const [checked, setChecked] = React.useState(false);
+
+  const anchorRef = React.useRef();
+
+  return (
+    <Box >
+      <Checkbox
+        checked={checked}
+        id="ref"
+        label="Private Board"
+        name="privacy"
+        ref={anchorRef}
+        onChange={({ checked }) => {
+          setOpen(true)
+          setChecked(checked);
+        }}
+      />
+      {open && (
+        <Flyout
+          anchor={anchorRef.current}
+          idealDirection="up"
+          onDismiss={() => setOpen(false)}
+          shouldFocus={false}
+        >
+          <Box padding={3}>
+            <Text weight="bold">Your board is now </Text>
+            <Text weight="bold">{checked ? 'private': 'public'}</Text>
+          </Box>
+        </Flyout>
+      )}
+    </Box>
+  );
+}
+`}
+  />
+);
+
 card(
   <Combination
     id="combinations"

packages/gestalt/src/Checkbox.js

@@ -16,6 +16,7 @@ type Props = {|
   checked?: boolean,
   disabled?: boolean,
   errorMessage?: string,
+  forwardedRef?: React.Ref<'input'>,
   hasError?: boolean,
   id: string,
   indeterminate?: boolean,
@@ -32,26 +33,34 @@ type Props = {|
   size?: 'sm' | 'md',
 |};
 
-export default function Checkbox({
-  checked = false,
-  disabled = false,
-  errorMessage,
-  hasError = false,
-  id,
-  indeterminate = false,
-  label,
-  name,
-  onChange,
-  onClick,
-  size = 'md',
-}: Props): React.Node {
-  const inputElement = React.useRef<?HTMLInputElement>(null);
+function Checkbox(props: Props): React.Node {
+  const {
+    checked = false,
+    disabled = false,
+    errorMessage,
+    forwardedRef,
+    hasError = false,
+    id,
+    indeterminate = false,
+    label,
+    name,
+    onChange,
+    onClick,
+    size = 'md',
+  } = props;
+
+  const innerRef = React.useRef(null);
+  // When using both forwardedRef and innerRef, React.useimperativehandle() allows a parent component
+  // that renders <Checkbox ref={inputRef} /> to call inputRef.current.focus()
+  // $FlowFixMe Flow thinks forwardedRef is a number, which is incorrect
+  React.useImperativeHandle(forwardedRef, () => innerRef.current);
+
   const [focused, setFocused] = React.useState(false);
   const [hovered, setHover] = React.useState(false);
 
   React.useEffect(() => {
-    if (inputElement && inputElement.current) {
-      inputElement.current.indeterminate = indeterminate;
+    if (innerRef && innerRef.current) {
+      innerRef.current.indeterminate = indeterminate;
     }
   }, [indeterminate]);
 
@@ -104,7 +113,7 @@ export default function Checkbox({
         marginRight={-1}
       >
         <Label htmlFor={id}>
-          <Box paddingX={1} position="relative">
+          <Box paddingX={1}>
             <input
               checked={checked}
               className={classnames(controlStyles.input, styleSize, {
@@ -119,7 +128,7 @@ export default function Checkbox({
               onFocus={() => setFocused(true)}
               onMouseEnter={handleHover}
               onMouseLeave={handleHover}
-              ref={inputElement}
+              ref={innerRef}
               type="checkbox"
             />
             <div
@@ -174,6 +183,12 @@ Checkbox.propTypes = {
   checked: PropTypes.bool,
   disabled: PropTypes.bool,
   errorMessage: PropTypes.string,
+  forwardedRef: PropTypes.oneOfType([
+    PropTypes.func,
+    PropTypes.shape({
+      current: PropTypes.any,
+    }),
+  ]),
   hasError: PropTypes.bool,
   id: PropTypes.string.isRequired,
   indeterminate: PropTypes.bool,
@@ -183,3 +198,18 @@ Checkbox.propTypes = {
   onClick: PropTypes.func,
   size: PropTypes.oneOf(['sm', 'md']),
 };
+
+function CheckboxWithRef(props, ref) {
+  return <Checkbox {...props} forwardedRef={ref} />;
+}
+
+CheckboxWithRef.displayName = 'ForwardRef(Checkbox)';
+
+const CheckboxWithForwardRef: React$AbstractComponent<
+  Props,
+  HTMLInputElement
+> = React.forwardRef<Props, HTMLInputElement>(CheckboxWithRef);
+
+CheckboxWithForwardRef.displayName = 'Checkbox';
+
+export default CheckboxWithForwardRef;

packages/gestalt/src/Checkbox.jsdom.test.js

@@ -3,21 +3,55 @@ import React from 'react';
 import { render } from '@testing-library/react';
 import Checkbox from './Checkbox.js';
 
-test('Checkbox handles click', () => {
-  const mockOnClick = jest.fn();
-  const mockOnChange = jest.fn();
-  const { getByLabelText } = render(
-    <form>
-      <label htmlFor="testcheckbox">Label</label>
+const mockOnClick = jest.fn();
+const mockOnChange = jest.fn();
+
+describe('Checkbox', () => {
+  it('Checkbox handles click', () => {
+    const { getByLabelText } = render(
+      <form>
+        <label htmlFor="testcheckbox">Label</label>
+        <Checkbox
+          size="sm"
+          id="testcheckbox"
+          onChange={mockOnChange}
+          onClick={mockOnClick}
+        />
+      </form>
+    );
+    getByLabelText('Label').click();
+    expect(mockOnClick).toHaveBeenCalled();
+    expect(mockOnChange).toHaveBeenCalled();
+  });
+
+  it('forwards a ref to <Box ref={ref}><input/></Box>', () => {
+    const ref = React.createRef();
+    render(
+      <Checkbox checked id="testcheckbox" onChange={mockOnChange} ref={ref} />
+    );
+    expect(ref.current instanceof HTMLInputElement).toEqual(true);
+    expect(ref.current?.checked).toEqual(true);
+  });
+
+  it('sets the innermost input to indeterminate with ref', () => {
+    const ref = React.createRef();
+    render(
       <Checkbox
-        size="sm"
+        indeterminate
         id="testcheckbox"
         onChange={mockOnChange}
-        onClick={mockOnClick}
+        ref={ref}
       />
-    </form>
-  );
-  getByLabelText('Label').click();
-  expect(mockOnClick).toHaveBeenCalled();
-  expect(mockOnChange).toHaveBeenCalled();
+    );
+    expect(ref.current instanceof HTMLInputElement).toEqual(true);
+    expect(ref.current?.indeterminate).toEqual(true);
+  });
+
+  it('sets the innermost input to indeterminate without ref', () => {
+    const { container } = render(
+      <Checkbox indeterminate id="testcheckbox" onChange={mockOnChange} />
+    );
+    const input = container.querySelector('input');
+    expect(input?.indeterminate).toBe(true);
+  });
 });

packages/gestalt/src/__snapshots__/Checkbox.test.js.snap

@@ -12,7 +12,7 @@ exports[`Checkbox 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}
@@ -62,7 +62,7 @@ exports[`Checkbox checked 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={true}
@@ -126,7 +126,7 @@ exports[`Checkbox disabled & checked 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={true}
@@ -190,7 +190,7 @@ exports[`Checkbox disabled 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}
@@ -240,7 +240,7 @@ exports[`Checkbox indeterminate 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}
@@ -304,7 +304,7 @@ exports[`Checkbox small 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}
@@ -354,7 +354,7 @@ exports[`Checkbox with error 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}
@@ -425,7 +425,7 @@ exports[`Checkbox without label 1`] = `
       htmlFor="id"
     >
       <div
-        className="box paddingX1 relative"
+        className="box paddingX1"
       >
         <input
           checked={false}