From 1c7c8d364bba2571cd783c90ee55fc61d9ec67c2 Mon Sep 17 00:00:00 2001
From: Braden MacDonald <braden@opencraft.com>
Date: Tue, 21 May 2024 15:35:52 -0700
Subject: [PATCH 1/3] feat: add typings for <Button>

---
 .../{Button.test.jsx => Button.test.tsx}      | 16 +++-
 ...tonGroup.test.jsx => ButtonGroup.test.tsx} |  0
 ...oolbar.test.jsx => ButtonToolbar.test.tsx} |  0
 ...ton.test.jsx.snap => Button.test.tsx.snap} | 21 +++++-
 ...est.jsx.snap => ButtonGroup.test.tsx.snap} |  0
 ...t.jsx.snap => ButtonToolbar.test.tsx.snap} |  0
 src/Button/{index.jsx => index.tsx}           | 75 +++++++++++++++----
 src/Chip/ChipIcon.tsx                         |  2 +-
 src/Chip/index.tsx                            | 10 +--
 src/Icon/index.d.ts                           |  6 +-
 src/Icon/index.jsx                            |  2 +-
 src/index.d.ts                                |  2 +-
 src/index.js                                  |  6 +-
 www/src/components/PageEditBtn/index.tsx      |  2 +-
 www/src/components/header/Header.tsx          |  2 +-
 www/src/components/header/Navbar.tsx          |  2 +-
 16 files changed, 110 insertions(+), 36 deletions(-)
 rename src/Button/{Button.test.jsx => Button.test.tsx} (84%)
 rename src/Button/{ButtonGroup.test.jsx => ButtonGroup.test.tsx} (100%)
 rename src/Button/{ButtonToolbar.test.jsx => ButtonToolbar.test.tsx} (100%)
 rename src/Button/__snapshots__/{Button.test.jsx.snap => Button.test.tsx.snap} (92%)
 rename src/Button/__snapshots__/{ButtonGroup.test.jsx.snap => ButtonGroup.test.tsx.snap} (100%)
 rename src/Button/__snapshots__/{ButtonToolbar.test.jsx.snap => ButtonToolbar.test.tsx.snap} (100%)
 rename src/Button/{index.jsx => index.tsx} (50%)

diff --git a/src/Button/Button.test.jsx b/src/Button/Button.test.tsx
similarity index 84%
rename from src/Button/Button.test.jsx
rename to src/Button/Button.test.tsx
index ebe19e0b55..8a3abc3af8 100644
--- a/src/Button/Button.test.jsx
+++ b/src/Button/Button.test.tsx
@@ -30,7 +30,7 @@ describe('<Button />', () => {
 
     it('renders with props iconAfter and size', () => {
       const tree = renderer.create((
-        <Button iconAfter={Close} size="md">Button</Button>
+        <Button iconAfter={Close} size="sm">Button</Button>
       )).toJSON();
       expect(tree).toMatchSnapshot();
     });
@@ -94,9 +94,21 @@ describe('<Button />', () => {
       });
 
       test('test button as hyperlink', () => {
-        render(<Button as={Hyperlink} destination="https://www.poop.com/💩">Button</Button>);
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const ref = (_current: HTMLAnchorElement) => {}; // Check typing of a ref - should not show type errors.
+        render(<Button as={Hyperlink} ref={ref} destination="https://www.poop.com/💩">Button</Button>);
         expect(screen.getByRole('link').getAttribute('href')).toEqual('https://www.poop.com/💩');
       });
     });
+
+    test('with size="inline"', () => {
+      const tree = renderer.create((
+        <p>
+          <span className="mr-1">2 items selected.</span>
+          <Button variant="link" size="inline">Clear</Button>
+        </p>
+      )).toJSON();
+      expect(tree).toMatchSnapshot();
+    });
   });
 });
diff --git a/src/Button/ButtonGroup.test.jsx b/src/Button/ButtonGroup.test.tsx
similarity index 100%
rename from src/Button/ButtonGroup.test.jsx
rename to src/Button/ButtonGroup.test.tsx
diff --git a/src/Button/ButtonToolbar.test.jsx b/src/Button/ButtonToolbar.test.tsx
similarity index 100%
rename from src/Button/ButtonToolbar.test.jsx
rename to src/Button/ButtonToolbar.test.tsx
diff --git a/src/Button/__snapshots__/Button.test.jsx.snap b/src/Button/__snapshots__/Button.test.tsx.snap
similarity index 92%
rename from src/Button/__snapshots__/Button.test.jsx.snap
rename to src/Button/__snapshots__/Button.test.tsx.snap
index 863a1f933e..2cfb8b2f61 100644
--- a/src/Button/__snapshots__/Button.test.jsx.snap
+++ b/src/Button/__snapshots__/Button.test.tsx.snap
@@ -55,13 +55,13 @@ exports[`<Button /> correct rendering renders with props iconAfter 1`] = `
 
 exports[`<Button /> correct rendering renders with props iconAfter and size 1`] = `
 <button
-  className="btn btn-primary btn-md"
+  className="btn btn-primary btn-sm"
   disabled={false}
   type="button"
 >
   Button
   <span
-    className="pgn__icon pgn__icon__md btn-icon-after"
+    className="pgn__icon pgn__icon__sm btn-icon-after"
   >
     <svg
       aria-hidden={true}
@@ -197,3 +197,20 @@ exports[`<Button /> correct rendering renders without props 1`] = `
   Button
 </button>
 `;
+
+exports[`<Button /> correct rendering with size="inline" 1`] = `
+<p>
+  <span
+    className="mr-1"
+  >
+    2 items selected.
+  </span>
+  <button
+    className="btn btn-link btn-inline"
+    disabled={false}
+    type="button"
+  >
+    Clear
+  </button>
+</p>
+`;
diff --git a/src/Button/__snapshots__/ButtonGroup.test.jsx.snap b/src/Button/__snapshots__/ButtonGroup.test.tsx.snap
similarity index 100%
rename from src/Button/__snapshots__/ButtonGroup.test.jsx.snap
rename to src/Button/__snapshots__/ButtonGroup.test.tsx.snap
diff --git a/src/Button/__snapshots__/ButtonToolbar.test.jsx.snap b/src/Button/__snapshots__/ButtonToolbar.test.tsx.snap
similarity index 100%
rename from src/Button/__snapshots__/ButtonToolbar.test.jsx.snap
rename to src/Button/__snapshots__/ButtonToolbar.test.tsx.snap
diff --git a/src/Button/index.jsx b/src/Button/index.tsx
similarity index 50%
rename from src/Button/index.jsx
rename to src/Button/index.tsx
index 13c444e9fa..2bd67ac3ce 100644
--- a/src/Button/index.jsx
+++ b/src/Button/index.tsx
@@ -1,32 +1,57 @@
 import React from 'react';
-import PropTypes from 'prop-types';
+import PropTypes, { type Requireable } from 'prop-types';
 import classNames from 'classnames';
-import BaseButton from 'react-bootstrap/Button';
-import BaseButtonGroup from 'react-bootstrap/ButtonGroup';
-import BaseButtonToolbar from 'react-bootstrap/ButtonToolbar';
+import BaseButton, { type ButtonProps as BaseButtonProps } from 'react-bootstrap/Button';
+import BaseButtonGroup, { type ButtonGroupProps as BaseButtonGroupProps } from 'react-bootstrap/ButtonGroup';
+import BaseButtonToolbar, { type ButtonToolbarProps } from 'react-bootstrap/ButtonToolbar';
+import { type BsPrefixRefForwardingComponent as ComponentWithAsProp } from 'react-bootstrap/esm/helpers';
+// @ts-ignore - we're not going to bother adding types for the deprecated button
 import ButtonDeprecated from './deprecated';
 
 import Icon from '../Icon';
 
-const Button = React.forwardRef(({
+interface ButtonProps extends Omit<BaseButtonProps, 'size'> {
+  /**
+   * An icon component to render. Example:
+   * ```
+   * import { Close } from '@openedx/paragon/icons';
+   * <Button iconBefore={Close}>Close</Button>
+   * ```
+   */
+  iconBefore?: React.ComponentType;
+  /**
+   * An icon component to render. Example:
+   * ```
+   * import { Close } from '@openedx/paragon/icons';
+   * <Button iconAfter={Close}>Close</Button>
+   * ```
+   */
+  iconAfter?: React.ComponentType;
+  size?: 'sm' | 'md' | 'lg' | 'inline';
+}
+
+type ButtonType = ComponentWithAsProp<'button', ButtonProps> & { Deprecated?: any };
+
+const Button: ButtonType = React.forwardRef<HTMLButtonElement, ButtonProps>(({
   children,
   iconAfter,
   iconBefore,
+  size,
   ...props
 }, ref) => (
   <BaseButton
+    size={size as 'sm' | 'lg' | undefined} // Bootstrap's <Button> types do not allow 'md' or 'inline', but we do.
     {...props}
     className={classNames(props.className)}
     ref={ref}
   >
-    {iconBefore && <Icon className="btn-icon-before" size={props.size} src={iconBefore} />}
+    {iconBefore && <Icon className="btn-icon-before" size={size} src={iconBefore} />}
     {children}
-    {iconAfter && <Icon className="btn-icon-after" size={props.size} src={iconAfter} />}
+    {iconAfter && <Icon className="btn-icon-after" size={size} src={iconAfter} />}
   </BaseButton>
 ));
 
 Button.propTypes = {
-  ...Button.propTypes,
   /** Specifies class name to apply to the button */
   className: PropTypes.string,
   /** Disables the Button, preventing mouse events, even if the underlying component is an `<a>` element */
@@ -52,10 +77,13 @@ Button.propTypes = {
   variant: PropTypes.string,
   /** An icon component to render.
   * Example import of a Paragon icon component: `import { Check } from '@openedx/paragon/icons';` */
-  iconBefore: PropTypes.oneOfType([PropTypes.elementType, PropTypes.node]),
+  iconBefore: PropTypes.elementType as Requireable<React.ComponentType>,
   /** An icon component to render.
   * Example import of a Paragon icon component: `import { Check } from '@openedx/paragon/icons';` */
-  iconAfter: PropTypes.oneOfType([PropTypes.elementType, PropTypes.node]),
+  iconAfter: PropTypes.elementType as Requireable<React.ComponentType>,
+  // The 'as' type casting above is required for TypeScript checking, because the 'PropTypes.elementType' type normally
+  // allows strings as a value (for use cases like 'div') but we don't support that for <Icon />/iconBefore/iconAfter.
+  // The React TypeScript type definitions are more specific (React.ComponentType vs React.ElementType).
 };
 
 Button.defaultProps = {
@@ -69,20 +97,29 @@ Button.defaultProps = {
 
 Button.Deprecated = ButtonDeprecated;
 
-function ButtonGroup(props) {
-  return <BaseButtonGroup {...props} />;
-}
-function ButtonToolbar(props) {
-  return <BaseButtonToolbar {...props} />;
+// We could just re-export 'ButtonGroup' and 'ButtonToolbar', but we currently
+// override them to add propTypes validation at runtime, since most Paragon
+// consumers aren't using TypeScript yet. We also force ButtonGroup's 'size'
+// prop to accept our custom values of 'md' and 'inline' which are used in
+// Paragon but not used in the base Bootstrap classes.
+
+interface ButtonGroupProps extends Omit<BaseButtonGroupProps, 'size'> {
+  size?: 'sm' | 'md' | 'lg' | 'inline';
 }
 
+const ButtonGroup: ComponentWithAsProp<'div', ButtonGroupProps> = (
+  React.forwardRef<HTMLButtonElement, ButtonGroupProps>(({ size, ...props }, ref) => (
+    <BaseButtonGroup size={size as 'sm' | 'lg'} {...props} ref={ref} />
+  ))
+);
+
 ButtonGroup.propTypes = {
   /** Specifies element type for this component. */
   as: PropTypes.elementType,
   /** An ARIA role describing the button group. */
   role: PropTypes.string,
   /** Specifies the size for all Buttons in the group. */
-  size: PropTypes.oneOf(['sm', 'md', 'lg']),
+  size: PropTypes.oneOf(['sm', 'md', 'lg', 'inline']),
   /** Display as a button toggle group. */
   toggle: PropTypes.bool,
   /** Specifies if the set of Buttons should appear vertically stacked. */
@@ -100,6 +137,12 @@ ButtonGroup.defaultProps = {
   size: 'md',
 };
 
+const ButtonToolbar: ComponentWithAsProp<'div', ButtonToolbarProps> = (
+  React.forwardRef<HTMLButtonElement, ButtonToolbarProps>((props, ref) => (
+    <BaseButtonToolbar {...props} ref={ref} />
+  ))
+);
+
 ButtonToolbar.propTypes = {
   /** An ARIA role describing the button group. */
   role: PropTypes.string,
diff --git a/src/Chip/ChipIcon.tsx b/src/Chip/ChipIcon.tsx
index a32692c5ce..87e08aa256 100644
--- a/src/Chip/ChipIcon.tsx
+++ b/src/Chip/ChipIcon.tsx
@@ -8,7 +8,7 @@ import { STYLE_VARIANTS } from './constants';
 
 export interface ChipIconProps {
   className: string,
-  src: React.ReactElement | Function,
+  src: React.ComponentType,
   onClick?: KeyboardEventHandler & MouseEventHandler,
   alt?: string,
   variant: string,
diff --git a/src/Chip/index.tsx b/src/Chip/index.tsx
index 23abfde5c7..0f78ab2059 100644
--- a/src/Chip/index.tsx
+++ b/src/Chip/index.tsx
@@ -1,5 +1,5 @@
 import React, { ForwardedRef, KeyboardEventHandler, MouseEventHandler } from 'react';
-import PropTypes from 'prop-types';
+import PropTypes, { type Requireable } from 'prop-types';
 import classNames from 'classnames';
 // @ts-ignore
 import { requiredWhen } from '../utils/propTypes';
@@ -15,9 +15,9 @@ export interface IChip {
   onClick?: KeyboardEventHandler & MouseEventHandler,
   className?: string,
   variant?: string,
-  iconBefore?: React.ReactElement | Function,
+  iconBefore?: React.ComponentType,
   iconBeforeAlt?: string,
-  iconAfter?: React.ReactElement | Function,
+  iconAfter?: React.ComponentType,
   iconAfterAlt?: string,
   onIconBeforeClick?: KeyboardEventHandler & MouseEventHandler,
   onIconAfterClick?: KeyboardEventHandler & MouseEventHandler,
@@ -111,7 +111,7 @@ Chip.propTypes = {
    *
    * `import { Check } from '@openedx/paragon/icons';`
    */
-  iconBefore: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  iconBefore: PropTypes.elementType as Requireable<React.ComponentType>,
   /** Specifies icon alt text. */
   iconBeforeAlt: requiredWhen(PropTypes.string, ['iconBefore', 'onIconBeforeClick']),
   /** A click handler for the `Chip` icon before. */
@@ -122,7 +122,7 @@ Chip.propTypes = {
    *
    * `import { Check } from '@openedx/paragon/icons';`
    */
-  iconAfter: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  iconAfter: PropTypes.elementType as Requireable<React.ComponentType>,
   /** Specifies icon alt text. */
   iconAfterAlt: requiredWhen(PropTypes.string, ['iconAfter', 'onIconAfterClick']),
   /** A click handler for the `Chip` icon after. */
diff --git a/src/Icon/index.d.ts b/src/Icon/index.d.ts
index 45505bb49a..b9d6f5d746 100644
--- a/src/Icon/index.d.ts
+++ b/src/Icon/index.d.ts
@@ -1,13 +1,15 @@
 import React from 'react';
 
 export interface IconProps extends React.ComponentPropsWithoutRef<'span'> {
-  src?: React.ReactElement | Function;
+  // Note: React.ComponentType is what we want here. React.ElementType would allow some element type strings like "div",
+  // but we only want to allow components like 'Add' (a specific icon component function/class)
+  src?: React.ComponentType;
   svgAttrs?: {
     'aria-label'?: string;
     'aria-labelledby'?: string;
   };
   id?: string | null;
-  size?: 'xs' | 'sm' | 'md' | 'lg';
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'inline';
   className?: string | string[];
   hidden?: boolean;
   screenReaderText?: React.ReactNode;
diff --git a/src/Icon/index.jsx b/src/Icon/index.jsx
index 6f0a7a3cf3..89403430f2 100644
--- a/src/Icon/index.jsx
+++ b/src/Icon/index.jsx
@@ -74,7 +74,7 @@ Icon.propTypes = {
    * An icon component to render.
    * Example import of a Paragon icon component: `import { Check } from '@openedx/paragon/icons';`
    */
-  src: PropTypes.oneOfType([PropTypes.element, PropTypes.elementType]),
+  src: PropTypes.elementType,
   /** HTML element attributes to pass through to the underlying svg element */
   svgAttrs: PropTypes.shape({
     'aria-label': PropTypes.string,
diff --git a/src/index.d.ts b/src/index.d.ts
index e4050de325..8cd1eaea8b 100644
--- a/src/index.d.ts
+++ b/src/index.d.ts
@@ -5,6 +5,7 @@
 // Things that have types
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 export { default as Bubble } from './Bubble';
+export { default as Button, ButtonGroup, ButtonToolbar } from './Button';
 export { default as Chip, CHIP_PGN_CLASS } from './Chip';
 export { default as ChipCarousel } from './ChipCarousel';
 export { default as Hyperlink, HYPER_LINK_EXTERNAL_LINK_ALT_TEXT, HYPER_LINK_EXTERNAL_LINK_TITLE } from './Hyperlink';
@@ -21,7 +22,6 @@ export const Avatar: any; // from './Avatar';
 export const AvatarButton: any; // from './AvatarButton';
 export const Badge: any; // from './Badge';
 export const Breadcrumb: any; // from './Breadcrumb';
-export const Button: any, ButtonGroup: any, ButtonToolbar: any; // from './Button';
 export const
   Card: any,
   CardColumns: any,
diff --git a/src/index.js b/src/index.js
index 2f1b794be4..2dbc760aba 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,10 +1,11 @@
-// To keep this file in sync with the .d.ts file, it's in the same order
-// and each line number is the same
+// Keep this file in sync with the .d.ts file (manually). It's in the same order
+// and each line number is the same, to make it easier.
 
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 // Things that have types
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 export { default as Bubble } from './Bubble';
+export { default as Button, ButtonGroup, ButtonToolbar } from './Button';
 export { default as Chip, CHIP_PGN_CLASS } from './Chip';
 export { default as ChipCarousel } from './ChipCarousel';
 export { default as Hyperlink, HYPER_LINK_EXTERNAL_LINK_ALT_TEXT, HYPER_LINK_EXTERNAL_LINK_TITLE } from './Hyperlink';
@@ -21,7 +22,6 @@ export { default as Avatar } from './Avatar';
 export { default as AvatarButton } from './AvatarButton';
 export { default as Badge } from './Badge';
 export { default as Breadcrumb } from './Breadcrumb';
-export { default as Button, ButtonGroup, ButtonToolbar } from './Button';
 export {
   default as Card,
   CardColumns,
diff --git a/www/src/components/PageEditBtn/index.tsx b/www/src/components/PageEditBtn/index.tsx
index ba22e8ab22..0433d4bccf 100644
--- a/www/src/components/PageEditBtn/index.tsx
+++ b/www/src/components/PageEditBtn/index.tsx
@@ -30,7 +30,7 @@ function PageEditBtn({ githubEditPath, isNavLink, ...props }: PageEditBtnProps)
     <Button
       size="sm"
       as={Hyperlink}
-      destination={githubEditPath}
+      destination={githubEditPath ?? ''}
       variant="tertiary"
       onClick={handlePageEditBtnClick}
       target="_blank"
diff --git a/www/src/components/header/Header.tsx b/www/src/components/header/Header.tsx
index 7aa1c67881..3918744f56 100644
--- a/www/src/components/header/Header.tsx
+++ b/www/src/components/header/Header.tsx
@@ -19,7 +19,7 @@ export interface IHeaderProps {
 function Header({ siteTitle, showMinimizedTitle }: IHeaderProps) {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const [isOpen, , close, toggle] = useToggle(false);
-  const [target, setTarget] = useState(null);
+  const [target, setTarget] = useState<HTMLButtonElement | null>(null);
   const { openSettings } = useContext(SettingsContext);
   const isMobile = useMediaQuery({ maxWidth: breakpoints.small.maxWidth });
 
diff --git a/www/src/components/header/Navbar.tsx b/www/src/components/header/Navbar.tsx
index 6b57b45f2a..a9306dd1bc 100644
--- a/www/src/components/header/Navbar.tsx
+++ b/www/src/components/header/Navbar.tsx
@@ -16,7 +16,7 @@ import Search from '../Search';
 export interface INavbar {
   siteTitle: string,
   onMenuClick: () => boolean,
-  setTarget: React.Dispatch<React.SetStateAction<null>>,
+  setTarget: React.Dispatch<React.SetStateAction<HTMLButtonElement | null>>,
   onSettingsClick: Function | undefined,
   menuIsOpen?: boolean,
   showMinimizedTitle?: boolean,

From 163776731e59cd02429be0f0870e60d3e281150a Mon Sep 17 00:00:00 2001
From: Braden MacDonald <braden@opencraft.com>
Date: Mon, 27 May 2024 14:51:45 -0700
Subject: [PATCH 2/3] chore: bump @types/react and @types/react-dom

---
 package-lock.json | 13 ++++++++-----
 package.json      |  4 ++--
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 6c038abf86..573cd47049 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -69,8 +69,8 @@
         "@testing-library/react-hooks": "^8.0.1",
         "@testing-library/user-event": "^13.5.0",
         "@types/jest": "^29.5.10",
-        "@types/react": "17.0.0",
-        "@types/react-dom": "17.0.11",
+        "@types/react": "^17",
+        "@types/react-dom": "^17.0.11",
         "@types/react-responsive": "^8.0.8",
         "@types/react-table": "^7.7.19",
         "@types/react-test-renderer": "^18.0.0",
@@ -8419,17 +8419,20 @@
       }
     },
     "node_modules/@types/react": {
-      "version": "17.0.0",
-      "license": "MIT",
+      "version": "17.0.80",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-17.0.80.tgz",
+      "integrity": "sha512-LrgHIu2lEtIo8M7d1FcI3BdwXWoRQwMoXOZ7+dPTW0lYREjmlHl3P0U1VD0i/9tppOuv8/sam7sOjx34TxSFbA==",
       "dependencies": {
         "@types/prop-types": "*",
+        "@types/scheduler": "^0.16",
         "csstype": "^3.0.2"
       }
     },
     "node_modules/@types/react-dom": {
       "version": "17.0.11",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-17.0.11.tgz",
+      "integrity": "sha512-f96K3k+24RaLGVu/Y2Ng3e1EbZ8/cVJvypZWd7cy0ofCBaf2lcM46xNhycMZ2xGwbBjRql7hOlZ+e2WlJ5MH3Q==",
       "dev": true,
-      "license": "MIT",
       "dependencies": {
         "@types/react": "*"
       }
diff --git a/package.json b/package.json
index 619080fe70..edbf3235bf 100644
--- a/package.json
+++ b/package.json
@@ -106,8 +106,8 @@
     "@testing-library/react-hooks": "^8.0.1",
     "@testing-library/user-event": "^13.5.0",
     "@types/jest": "^29.5.10",
-    "@types/react": "17.0.0",
-    "@types/react-dom": "17.0.11",
+    "@types/react": "^17.0.80",
+    "@types/react-dom": "^17.0.11",
     "@types/react-responsive": "^8.0.8",
     "@types/react-table": "^7.7.19",
     "@types/react-test-renderer": "^18.0.0",

From 66f85cb2f13a98102cf785514287bc0fa449c310 Mon Sep 17 00:00:00 2001
From: Braden MacDonald <braden@opencraft.com>
Date: Wed, 29 May 2024 11:32:21 -0700
Subject: [PATCH 3/3] feat: re-export bootstrap helpers as ComponentWithAsProp,
 BsPropsWithAs

---
 package-lock.json                  |  2 +-
 src/Button/index.tsx               |  2 +-
 src/utils/types/bootstrap.test.tsx | 86 ++++++++++++++++++++++++++++++
 src/utils/types/bootstrap.ts       | 43 +++++++++++++++
 www/tsconfig.json                  |  2 +-
 5 files changed, 132 insertions(+), 3 deletions(-)
 create mode 100644 src/utils/types/bootstrap.test.tsx
 create mode 100644 src/utils/types/bootstrap.ts

diff --git a/package-lock.json b/package-lock.json
index 573cd47049..118089f654 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -69,7 +69,7 @@
         "@testing-library/react-hooks": "^8.0.1",
         "@testing-library/user-event": "^13.5.0",
         "@types/jest": "^29.5.10",
-        "@types/react": "^17",
+        "@types/react": "^17.0.80",
         "@types/react-dom": "^17.0.11",
         "@types/react-responsive": "^8.0.8",
         "@types/react-table": "^7.7.19",
diff --git a/src/Button/index.tsx b/src/Button/index.tsx
index 2bd67ac3ce..c22e3c3e28 100644
--- a/src/Button/index.tsx
+++ b/src/Button/index.tsx
@@ -4,7 +4,7 @@ import classNames from 'classnames';
 import BaseButton, { type ButtonProps as BaseButtonProps } from 'react-bootstrap/Button';
 import BaseButtonGroup, { type ButtonGroupProps as BaseButtonGroupProps } from 'react-bootstrap/ButtonGroup';
 import BaseButtonToolbar, { type ButtonToolbarProps } from 'react-bootstrap/ButtonToolbar';
-import { type BsPrefixRefForwardingComponent as ComponentWithAsProp } from 'react-bootstrap/esm/helpers';
+import type { ComponentWithAsProp } from '../utils/types/bootstrap';
 // @ts-ignore - we're not going to bother adding types for the deprecated button
 import ButtonDeprecated from './deprecated';
 
diff --git a/src/utils/types/bootstrap.test.tsx b/src/utils/types/bootstrap.test.tsx
new file mode 100644
index 0000000000..0346c5d2b4
--- /dev/null
+++ b/src/utils/types/bootstrap.test.tsx
@@ -0,0 +1,86 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import React from 'react';
+import type { BsPropsWithAs, ComponentWithAsProp } from './bootstrap';
+
+// Note: these are type-only tests. They don't actually do much at runtime; the important checks are at transpile time.
+
+describe('BsPropsWithAs', () => {
+  interface Props<As extends React.ElementType = 'table'> extends BsPropsWithAs<As> {
+    otherProp?: number;
+  }
+
+  it('defines optional bsPrefix, className, and as but no other props', () => {
+    const checkProps = <As extends React.ElementType = 'table'>(_props: Props<As>) => {};
+    // These are all valid props per the prop definition:
+    checkProps({ });
+    checkProps({ bsPrefix: 'bs' });
+    checkProps({ className: 'foo bar' });
+    checkProps({ as: 'tr' });
+    checkProps({ className: 'foo bar', as: 'button', otherProp: 15 });
+    // But these are all invalid:
+    // @ts-expect-error
+    checkProps({ newProp: 10 });
+    // @ts-expect-error
+    checkProps({ onClick: () => {} });
+    // @ts-expect-error
+    checkProps({ id: 'id' });
+    // @ts-expect-error
+    checkProps({ children: <tr /> });
+  });
+});
+
+describe('ComponentWithAsProp', () => {
+  interface MyProps extends BsPropsWithAs {
+    customProp?: string;
+  }
+  const MyComponent: ComponentWithAsProp<'div', MyProps> = (
+    React.forwardRef<HTMLDivElement, MyProps>(
+      ({ as: Inner = 'div', ...props }, ref) => <Inner {...props} ref={ref} />,
+    )
+  );
+
+  // eslint-disable-next-line react/function-component-definition
+  const CustomComponent: React.FC<{ requiredProp: string }> = () => <span />;
+
+  it('is defined to wrap a <div> by default, and accepts related props', () => {
+    // This is valid - by default it is a DIV so accepts props and ref related to DIV:
+    const divClick: React.MouseEventHandler<HTMLDivElement> = () => {};
+    const divRef: React.RefObject<HTMLDivElement> = { current: null };
+    const valid = <MyComponent ref={divRef} onClick={divClick} customProp="foo" />;
+  });
+
+  it('is defined to wrap a <div> by default, and rejects unrelated props', () => {
+    const btnRef: React.RefObject<HTMLButtonElement> = { current: null };
+    // @ts-expect-error because the ref is to a <button> ref, but this is wrapping a <div>
+    const invalidRef = <MyComponent ref={btnRef} customProp="foo" />;
+
+    const btnClick: React.MouseEventHandler<HTMLButtonElement> = () => {};
+    // @ts-expect-error because the handler is for a <button> event, but this is wrapping a <div>
+    const invalidClick = <MyComponent onClick={btnClick} />;
+  });
+
+  it('can be changed to wrap a <canvas>, and accepts related props', () => {
+    const canvasClick: React.MouseEventHandler<HTMLCanvasElement> = () => {};
+    const canvasRef: React.RefObject<HTMLCanvasElement> = { current: null };
+    const valid = <MyComponent as="canvas" ref={canvasRef} onClick={canvasClick} customProp="foo" />;
+  });
+
+  it('can be changed to wrap a <canvas>, and rejects unrelated props', () => {
+    const btnRef: React.RefObject<HTMLButtonElement> = { current: null };
+    // @ts-expect-error because the ref is to a <button> ref, but this is wrapping an <canvas>
+    const invalidRef = <MyComponent as="canvas" ref={btnRef} customProp="foo" />;
+
+    const btnClick: React.MouseEventHandler<HTMLButtonElement> = () => {};
+    // @ts-expect-error because the handler is for a <button> event, but this is wrapping an <canvas>
+    const invalidClick = <MyComponent as="canvas" onClick={btnClick} />;
+  });
+
+  it('can be changed to wrap a custom component, and accepts related props', () => {
+    const valid = <MyComponent as={CustomComponent} requiredProp="hello" />;
+  });
+
+  it('can be changed to wrap a custom component, and rejects unrelated props', () => {
+    // @ts-expect-error The onClick prop has not been declared for our custom component.
+    const valid = <MyComponent as={CustomComponent} requiredProp="hello" onClick={() => {}} />;
+  });
+});
diff --git a/src/utils/types/bootstrap.ts b/src/utils/types/bootstrap.ts
new file mode 100644
index 0000000000..2d05bbaf78
--- /dev/null
+++ b/src/utils/types/bootstrap.ts
@@ -0,0 +1,43 @@
+/**
+ * Types related to bootstrap components
+ */
+import React from 'react';
+
+import type { BsPrefixProps, BsPrefixRefForwardingComponent } from 'react-bootstrap/esm/helpers';
+
+/**
+ * Type helper for defining props of a component that wraps a bootstrap
+ * component. This type defines three props:
+ *    1. `className`: this component accepts additional CSS classes.
+ *    2. `bsPrefix`: locally change the class name prefix used for this component.
+ *    3. `as`: optionally specify which HTML element or Component is used, e.g. `"div"`
+ *
+ * This type assumes no `children` are allowed, but you can extend it to allow children.
+ */
+export type BsPropsWithAs<As extends React.ElementType = React.ElementType> = BsPrefixProps<As>;
+
+/**
+ * This is a helper that can be used to define the type of a Paragon component
+ * that accepts an `as` prop.
+ *
+ * It:
+ *   - assumes you are using `forwardRef`, and sets the type of the `ref` prop
+ *     to match the type of the component passed in the `as` prop.
+ *   - assumes you are passing all unused props to the component, so adds any
+ *     props from the `as` component type to the props you specify as `Props`.
+ *
+ * Example;
+ * ```
+ * interface MyProps extends BsPropsWithAs {
+ *   customProp?: string;
+ * }
+ * export const MyComponent: ComponentWithAsProp<'div', MyProps> = (
+ *   React.forwardRef<HTMLDivElement, MyProps>(
+ *     ({ as: Inner = 'div', ...props }, ref) => <Inner {...props} ref={ref} />,
+ *   )
+ * );
+ * ```
+ * Note that you need to define the default (e.g. `'div'`) in three different places.
+ */
+export type ComponentWithAsProp<DefaultElementType extends React.ElementType, Props>
+  = BsPrefixRefForwardingComponent<DefaultElementType, Props>;
diff --git a/www/tsconfig.json b/www/tsconfig.json
index 35e06753d6..6949812b78 100644
--- a/www/tsconfig.json
+++ b/www/tsconfig.json
@@ -1,7 +1,7 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "rootDir": "src",
+    "rootDir": "../",
     "resolveJsonModule": true,
     "noImplicitAny": false,
     "paths": {