ContextualHelp: Update type descriptions and forwardRef (#2836)

* add ref and update export

* add JSDoc to types

* add description to placement prop

Author: reidbarber

packages/@react-spectrum/contextualhelp/package.json

@@ -38,6 +38,7 @@
     "@react-spectrum/dialog": "^3.3.4",
     "@react-spectrum/utils": "^3.6.2",
     "@react-types/contextualhelp": "3.0.0-alpha.1",
+    "@react-types/shared": "^3.10.1",
     "@spectrum-icons/workflow": "^3.2.1"
   },
   "devDependencies": {

packages/@react-spectrum/contextualhelp/src/ContextualHelp.tsx

@@ -12,6 +12,7 @@
 
 import {ActionButton} from '@react-spectrum/button';
 import {Dialog, DialogTrigger} from '@react-spectrum/dialog';
+import {FocusableRef} from '@react-types/shared';
 import HelpOutline from '@spectrum-icons/workflow/HelpOutline';
 import helpStyles from './contextualhelp.css';
 import InfoOutline from '@spectrum-icons/workflow/InfoOutline';
@@ -22,12 +23,13 @@ import {SlotProvider} from '@react-spectrum/utils';
 import {SpectrumContextualHelpProps} from '@react-types/contextualhelp';
 import {useMessageFormatter} from '@react-aria/i18n';
 
-function ContextualHelp(props: SpectrumContextualHelpProps) {
+function ContextualHelp(props: SpectrumContextualHelpProps, ref: FocusableRef<HTMLButtonElement>) {
   let {
     variant = 'help',
     placement = 'bottom start',
     children,
-    ...otherProps} = props;
+    ...otherProps
+  } = props;
 
   let formatMessage = useMessageFormatter(intlMessages);
 
@@ -41,6 +43,7 @@ function ContextualHelp(props: SpectrumContextualHelpProps) {
   return (
     <DialogTrigger type="popover" placement={placement} hideArrow {...otherProps}>
       <ActionButton
+        ref={ref}
         UNSAFE_className={helpStyles['react-spectrum-ContextualHelp-button']}
         isQuiet
         aria-label={formatMessage('open')}>
@@ -51,12 +54,12 @@ function ContextualHelp(props: SpectrumContextualHelpProps) {
           {children}
         </Dialog>
       </SlotProvider>
-
     </DialogTrigger>
   );
 }
 
 /**
  * Contextual help shows a user extra information about the state of an adjacent component, or a total view.
  */
-export {ContextualHelp};
+let _ContextualHelp = React.forwardRef(ContextualHelp);
+export {_ContextualHelp as ContextualHelp};

packages/@react-types/contextualhelp/src/index.d.ts

@@ -10,12 +10,22 @@
  * governing permissions and limitations under the License.
  */
 
-import {OverlayTriggerProps, PositionProps} from '@react-types/overlays';
+import {OverlayTriggerProps, Placement, PositionProps} from '@react-types/overlays';
 import {ReactNode} from 'react';
 
 export interface SpectrumContextualHelpProps extends OverlayTriggerProps, PositionProps {
-  /** Contents of the Contextual Help popover. */
+  /**
+   * Contents of the Contextual Help popover.
+   */
   children: ReactNode,
-  /** Indicates whether contents are informative or provides helpful guidance. */
-  variant?: 'help' | 'info'
+  /**
+   * Indicates whether contents are informative or provides helpful guidance.
+   * @default 'help'
+   */
+  variant?: 'help' | 'info',
+  /**
+   * The placement of the popover with respect to the action button.
+   * @default 'bottom start'
+   */
+  placement?: Placement
 }