chore: prop types checker for destination hyperlink prop

src/Hyperlink/Hyperlink.test.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 import { render } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
-import Hyperlink from '.';
+import Hyperlink, { HyperlinkProps } from '.';
 
-const destination = 'destination';
+const destination = 'http://destination.example';
 const content = 'content';
 const onClick = jest.fn();
 const props = {
@@ -20,9 +20,25 @@ const externalLinkProps = {
   ...props,
 };
 
+interface LinkProps extends HyperlinkProps {
+  to: string;
+}
+
+function Link({ to, children, ...rest }: LinkProps) {
+  return (
+    <a
+      data-testid="custom-hyperlink-element"
+      href={to}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}
+
 describe('correct rendering', () => {
   beforeEach(() => {
-    onClick.mockClear();
+    jest.clearAllMocks();
   });
 
   it('renders Hyperlink', async () => {
@@ -40,6 +56,21 @@ describe('correct rendering', () => {
     expect(onClick).toHaveBeenCalledTimes(1);
   });
 
+  it('renders with custom element type via "as" prop', () => {
+    const propsWithoutDestination = {
+      to: destination, // `to` simulates common `Link` components' prop
+    };
+    const { getByRole } = render(<Hyperlink as={Link} {...propsWithoutDestination}>{content}</Hyperlink>);
+    const wrapper = getByRole('link');
+    expect(wrapper).toBeInTheDocument();
+
+    expect(wrapper).toHaveClass('pgn__hyperlink');
+    expect(wrapper).toHaveClass('standalone-link');
+    expect(wrapper).toHaveTextContent(content);
+    expect(wrapper).toHaveAttribute('href', destination);
+    expect(wrapper).toHaveAttribute('target', '_self');
+  });
+
   it('renders an underlined Hyperlink', async () => {
     const { getByRole } = render(<Hyperlink isInline {...props}>{content}</Hyperlink>);
     const wrapper = getByRole('link');

src/Hyperlink/README.md

@@ -101,15 +101,13 @@ notes: |
 </div>
 ```
 
-## with custom link element
+## with custom link element (e.g., using a router)
 
 ``Hyperlink`` typically relies on the standard HTML anchor tag (i.e., ``a``); however, this behavior may be overriden when the destination link is to an internal route where it should be using routing instead (e.g., ``Link`` from React Router).
 
 ```jsx live
 <Hyperlink
   as={GatsbyLink}
-  // `destination` is still a required prop even though the `to` takes precedence.
-  destination="/components/button"
   to="/components/button"
 >
   Button

src/Hyperlink/index.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { forwardRef } from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
 import {
@@ -7,13 +7,15 @@ import {
 } from 'react-bootstrap/esm/helpers';
 import { Launch } from '../../icons';
 import Icon from '../Icon';
+// @ts-ignore
+import { customPropTypeRequirement } from '../utils/propTypes/utils';
 
 export const HYPER_LINK_EXTERNAL_LINK_ALT_TEXT = 'in a new tab';
 export const HYPER_LINK_EXTERNAL_LINK_TITLE = 'Opens in a new tab';
 
-interface HyperlinkProps extends BsPrefixProps, Omit<React.ComponentPropsWithRef<'a'>, 'href' | 'target'> {
+export interface HyperlinkProps extends BsPrefixProps, Omit<React.ComponentPropsWithRef<'a'>, 'href' | 'target'> {
   /** specifies the URL */
-  destination: string;
+  destination?: string;
   /** Content of the hyperlink */
   children: React.ReactNode;
   /** Custom class names for the hyperlink */
@@ -31,9 +33,9 @@ interface HyperlinkProps extends BsPrefixProps, Omit<React.ComponentPropsWithRef
   target?: '_blank' | '_self';
 }
 
-type HyperlinkType = ComponentWithAsProp<'a', HyperlinkProps>;
+export type HyperlinkType = ComponentWithAsProp<'a', HyperlinkProps>;
 
-const Hyperlink: HyperlinkType = React.forwardRef<HTMLAnchorElement, HyperlinkProps>(({
+const Hyperlink: HyperlinkType = forwardRef<HTMLAnchorElement, HyperlinkProps>(({
   as: Component = 'a',
   className,
   destination,
@@ -83,6 +85,11 @@ const Hyperlink: HyperlinkType = React.forwardRef<HTMLAnchorElement, HyperlinkPr
     }
   }
 
+  const additionalProps: Record<string, any> = { ...attrs };
+  if (destination) {
+    additionalProps.href = destination;
+  }
+
   return (
     <Component
       ref={ref}
@@ -95,10 +102,9 @@ const Hyperlink: HyperlinkType = React.forwardRef<HTMLAnchorElement, HyperlinkPr
         },
         className,
       )}
-      href={destination}
       target={target}
       onClick={onClick}
-      {...attrs}
+      {...additionalProps}
     >
       {children}
       {externalLinkIcon}
@@ -108,9 +114,10 @@ const Hyperlink: HyperlinkType = React.forwardRef<HTMLAnchorElement, HyperlinkPr
 
 Hyperlink.defaultProps = {
   as: 'a',
+  destination: undefined,
   className: undefined,
   target: '_self',
-  onClick: () => {},
+  onClick: undefined,
   externalLinkAlternativeText: HYPER_LINK_EXTERNAL_LINK_ALT_TEXT,
   externalLinkTitle: HYPER_LINK_EXTERNAL_LINK_TITLE,
   variant: 'default',
@@ -121,8 +128,14 @@ Hyperlink.defaultProps = {
 Hyperlink.propTypes = {
   /** specifies the component element type to render for the hyperlink */
   as: PropTypes.elementType,
-  /** specifies the URL */
-  destination: PropTypes.string.isRequired,
+  /** specifies the URL; required iff `as` prop is a standard anchor tag */
+  destination: customPropTypeRequirement(
+    PropTypes.string,
+    ({ as }: Partial<HyperlinkProps>) => as && as === 'a',
+    // "[`destination` is required when]..."
+    'the `as` prop is a standard anchor element (i.e., "a")',
+  ),
+  // destination: PropTypes.string.isRequired,
   /** Content of the hyperlink */
   children: PropTypes.node.isRequired,
   /** Custom class names for the hyperlink */