@openedx/paragon 23.0.0-alpha.1 → 23.0.0-alpha.3

package/src/Hyperlink/{index.jsx → index.tsx}

@@ -1,29 +1,45 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
-import isRequiredIf from 'react-proptype-conditional-require';
 import { Launch } from '../../icons';
 import Icon from '../Icon';
 
-import withDeprecatedProps, { DeprTypes } from '../withDeprecatedProps';
-
 export const HYPER_LINK_EXTERNAL_LINK_ALT_TEXT = 'in a new tab';
 export const HYPER_LINK_EXTERNAL_LINK_TITLE = 'Opens in a new tab';
 
-const Hyperlink = React.forwardRef((props, ref) => {
-  const {
-    className,
-    destination,
-    children,
-    target,
-    onClick,
-    externalLinkAlternativeText,
-    externalLinkTitle,
-    variant,
-    isInline,
-    showLaunchIcon,
-    ...attrs
-  } = props;
+interface Props extends Omit<React.ComponentPropsWithRef<'a'>, 'href' | 'target'> {
+  /** specifies the URL */
+  destination: string;
+  /** Content of the hyperlink */
+  children: React.ReactNode;
+  /** Custom class names for the hyperlink */
+  className?: string;
+  /** Alt text for the icon indicating that this link opens in a new tab, if target="_blank". e.g. _("in a new tab") */
+  externalLinkAlternativeText?: string;
+  /** Tooltip text for the "opens in new tab" icon, if target="_blank". e.g. _("Opens in a new tab"). */
+  externalLinkTitle?: string;
+  /** type of hyperlink */
+  variant?: 'default' | 'muted' | 'brand';
+  /** Display the link with an underline. By default, it is only underlined on hover. */
+  isInline?: boolean;
+  /** specify if we need to show launch Icon. By default, it will be visible. */
+  showLaunchIcon?: boolean;
+  target?: '_blank' | '_self';
+}
+
+const Hyperlink = React.forwardRef<HTMLAnchorElement, Props>(({
+  className,
+  destination,
+  children,
+  target,
+  onClick,
+  externalLinkAlternativeText,
+  externalLinkTitle,
+  variant,
+  isInline,
+  showLaunchIcon,
+  ...attrs
+}, ref) => {
   let externalLinkIcon;
 
   if (target === '_blank') {
@@ -105,32 +121,20 @@ Hyperlink.propTypes = {
    * loaded into the same browsing context as the current one.
    * If the target is `_blank` (opening a new window) `rel='noopener'` will be added to the anchor tag to prevent
    * any potential [reverse tabnabbing attack](https://www.owasp.org/index.php/Reverse_Tabnabbing).
-  */
-  target: PropTypes.string,
+   */
+  target: PropTypes.oneOf(['_blank', '_self']),
   /** specifies the callback function when the link is clicked */
   onClick: PropTypes.func,
-  /** specifies the text for links with a `_blank` target (which loads the URL in a new browsing context). */
-  externalLinkAlternativeText: isRequiredIf(
-    PropTypes.string,
-    props => props.target === '_blank',
-  ),
-  /** specifies the title for links with a `_blank` target (which loads the URL in a new browsing context). */
-  externalLinkTitle: isRequiredIf(
-    PropTypes.string,
-    props => props.target === '_blank',
-  ),
+  /** Alt text for the icon indicating that this link opens in a new tab, if target="_blank". e.g. _("in a new tab") */
+  externalLinkAlternativeText: PropTypes.string,
+  /** Tooltip text for the "opens in new tab" icon, if target="_blank". e.g. _("Opens in a new tab"). */
+  externalLinkTitle: PropTypes.string,
   /** type of hyperlink */
   variant: PropTypes.oneOf(['default', 'muted', 'brand']),
-  /** specify the link style. By default, it will be underlined. */
+  /** Display the link with an underline. By default, it is only underlined on hover. */
   isInline: PropTypes.bool,
   /** specify if we need to show launch Icon. By default, it will be visible. */
   showLaunchIcon: PropTypes.bool,
 };
 
-export default withDeprecatedProps(Hyperlink, 'Hyperlink', {
-  /** specifies the text or element that a URL should be associated with */
-  content: {
-    deprType: DeprTypes.MOVED,
-    newName: 'children',
-  },
-});
+export default Hyperlink;

package/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;

package/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,

package/src/IconButton/{IconButton.test.jsx → IconButton.test.tsx}

@@ -11,21 +11,27 @@ describe('<IconButton />', () => {
   const alt = 'alternative';
   const iconAs = Icon;
   const src = InfoOutline;
-  const variant = 'secondary';
+  const variant = 'secondary' as const;
   const props = {
     alt,
     src,
     iconAs,
     variant,
   };
-  const iconParams = {
+  const deprecatedFontAwesomeExample = {
     prefix: 'pgn',
     iconName: 'InfoOutlineIcon',
     icon: [InfoOutline],
   };
   it('renders with required props', () => {
     const tree = renderer.create((
-      <IconButton icon={iconParams} alt={alt} />
+      <IconButton iconAs={Icon} src={InfoOutline} alt={alt} />
+    )).toJSON();
+    expect(tree).toMatchSnapshot();
+  });
+  it('renders with deprecated props', () => {
+    const tree = renderer.create((
+      <IconButton icon={deprecatedFontAwesomeExample} alt={alt} />
     )).toJSON();
     expect(tree).toMatchSnapshot();
   });
@@ -94,4 +100,19 @@ describe('<IconButton />', () => {
       expect(spy2).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe('<IconButton.IconButtonWithTooltip>', () => {
+    it('renders with required props', () => {
+      const tree = renderer.create((
+        <IconButton.IconButtonWithTooltip
+          iconAs={Icon}
+          src={InfoOutline}
+          alt={alt}
+          tooltipContent="Hello"
+          tooltipPlacement="left-end"
+        />
+      )).toJSON();
+      expect(tree).toMatchSnapshot();
+    });
+  });
 });

package/src/IconButton/__snapshots__/IconButton.test.tsx.snap

@@ -0,0 +1,90 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<IconButton /> <IconButton.IconButtonWithTooltip> renders with required props 1`] = `
+<button
+  aria-label="alternative"
+  className="btn-icon btn-icon-primary btn-icon-md"
+  onBlur={[Function]}
+  onClick={[Function]}
+  onFocus={[Function]}
+  onMouseOut={[Function]}
+  onMouseOver={[Function]}
+  type="button"
+>
+  <span
+    className="btn-icon__icon-container"
+  >
+    <span
+      className="pgn__icon btn-icon__icon"
+    >
+      <svg
+        aria-hidden={true}
+        fill="none"
+        focusable={false}
+        height={24}
+        role="img"
+        viewBox="0 0 24 24"
+        width={24}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M11 7h2v2h-2V7Zm0 4h2v6h-2v-6Zm1-9C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2Zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8Z"
+          fill="currentColor"
+        />
+      </svg>
+    </span>
+  </span>
+</button>
+`;
+
+exports[`<IconButton /> renders with deprecated props 1`] = `
+<button
+  aria-label="alternative"
+  className="btn-icon btn-icon-primary btn-icon-md"
+  onClick={[Function]}
+  type="button"
+>
+  <span
+    className="btn-icon__icon-container"
+  >
+    <span
+      aria-hidden={true}
+      className="btn-icon__icon"
+      id="Icon1"
+    />
+  </span>
+</button>
+`;
+
+exports[`<IconButton /> renders with required props 1`] = `
+<button
+  aria-label="alternative"
+  className="btn-icon btn-icon-primary btn-icon-md"
+  onClick={[Function]}
+  type="button"
+>
+  <span
+    className="btn-icon__icon-container"
+  >
+    <span
+      className="pgn__icon btn-icon__icon"
+    >
+      <svg
+        aria-hidden={true}
+        fill="none"
+        focusable={false}
+        height={24}
+        role="img"
+        viewBox="0 0 24 24"
+        width={24}
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M11 7h2v2h-2V7Zm0 4h2v6h-2v-6Zm1-9C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2Zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8Z"
+          fill="currentColor"
+        />
+      </svg>
+    </span>
+  </span>
+</button>
+`;

package/src/IconButton/{index.jsx → index.tsx}

@@ -1,12 +1,44 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
-
+import { type Placement } from 'react-bootstrap/Overlay';
 import Icon from '../Icon';
 import { OverlayTrigger } from '../Overlay';
 import Tooltip from '../Tooltip';
 
-const IconButton = React.forwardRef(({
+interface Props extends React.HTMLAttributes<HTMLButtonElement> {
+  iconAs?: React.ComponentType<any>,
+  /** Additional CSS class[es] to apply to this button */
+  className?: string;
+  /** Alt text for your icon. For best practice, avoid using alt text to describe
+   * the image in the `IconButton`. Instead, we recommend describing the function
+   * of the button. */
+  alt: string;
+  /** Changes icon styles for dark background */
+  invertColors?: boolean;
+  /** An icon component to render. Example import of a Paragon icon component:
+   * `import { Check } from '@openedx/paragon/icons';`
+   * */
+  // 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;
+  /** Extra class names that will be added to the icon */
+  iconClassNames?: string;
+  /** Click handler for the button */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  /** whether to show the `IconButton` in an active state, whose styling is distinct from default state */
+  isActive?: boolean;
+  /** @deprecated Using FontAwesome icons is deprecated. Instead, pass iconAs={Icon} src={...} */
+  icon?: { prefix?: string; iconName?: string, icon?: any[] },
+  /** Type of button (uses Bootstrap options) */
+  variant?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'light' | 'dark' | 'black' | 'brand';
+  /** size of button to render */
+  size?: 'sm' | 'md' | 'inline';
+  /** no children */
+  children?: never;
+}
+
+const IconButton = React.forwardRef<HTMLButtonElement, Props>(({
   className,
   alt,
   invertColors,
@@ -18,6 +50,7 @@ const IconButton = React.forwardRef(({
   variant,
   iconAs,
   isActive,
+  children, // unused, just here because we don't want it to be part of 'attrs'
   ...attrs
 }, ref) => {
   const invert = invertColors ? 'inverse-' : '';
@@ -42,11 +75,13 @@ const IconButton = React.forwardRef(({
       {...attrs}
     >
       <span className="btn-icon__icon-container">
-        <IconComponent
-          className={classNames('btn-icon__icon', iconClassNames)}
-          icon={icon}
-          src={src}
-        />
+        {IconComponent && (
+          <IconComponent
+            className={classNames('btn-icon__icon', iconClassNames)}
+            icon={icon as any}
+            src={src}
+          />
+        )}
       </span>
     </button>
   );
@@ -54,7 +89,7 @@ const IconButton = React.forwardRef(({
 
 IconButton.defaultProps = {
   iconAs: Icon,
-  src: null,
+  src: undefined,
   icon: undefined,
   iconClassNames: undefined,
   className: undefined,
@@ -63,17 +98,18 @@ IconButton.defaultProps = {
   size: 'md',
   onClick: () => {},
   isActive: false,
+  children: undefined,
 };
 
 IconButton.propTypes = {
   /** A custom class name. */
   className: PropTypes.string,
   /** Component that renders the icon, currently defaults to `Icon` */
-  iconAs: PropTypes.elementType,
+  iconAs: PropTypes.elementType as any,
   /** An icon component to render. Example import of a Paragon icon component:
-   * `import { Check } from '@openedx/paragon/dist/icon';`
+   * `import { Check } from '@openedx/paragon/icons';`
    * */
-  src: PropTypes.oneOfType([PropTypes.element, PropTypes.elementType]),
+  src: PropTypes.elementType as any,
   /** Alt text for your icon. For best practice, avoid using alt text to describe
    * the image in the `IconButton`. Instead, we recommend describing the function
    * of the button. */
@@ -86,7 +122,7 @@ IconButton.propTypes = {
     iconName: PropTypes.string,
     // eslint-disable-next-line react/forbid-prop-types
     icon: PropTypes.array,
-  }),
+  }) as any,
   /** Extra class names that will be added to the icon */
   iconClassNames: PropTypes.string,
   /** Click handler for the button */
@@ -99,38 +135,40 @@ IconButton.propTypes = {
   isActive: PropTypes.bool,
 };
 
+interface PropsWithTooltip extends Props {
+  /** choose from https://popper.js.org/docs/v2/constructors/#options */
+  tooltipPlacement: Placement,
+  /** any content to pass to tooltip content area */
+  tooltipContent: React.ReactNode,
+}
+
 /**
- *
- * @param { object } args Arguments
- * @param { string } args.tooltipPlacement choose from https://popper.js.org/docs/v2/constructors/#options
- * @param { React.Component } args.tooltipContent any content to pass to tooltip content area
- * @returns { IconButton } a button wrapped in overlaytrigger
+ * An icon button wrapped in overlaytrigger to display a tooltip.
  */
 function IconButtonWithTooltip({
-  tooltipPlacement, tooltipContent, variant, invertColors, ...props
-}) {
-  const invert = invertColors ? 'inverse-' : '';
+  tooltipPlacement, tooltipContent, ...props
+}: PropsWithTooltip) {
+  const invert = props.invertColors ? 'inverse-' : '';
   return (
     <OverlayTrigger
       placement={tooltipPlacement}
       overlay={(
         <Tooltip
           id={`iconbutton-tooltip-${tooltipPlacement}`}
-          variant={invert ? 'light' : ''}
+          variant={invert ? 'light' : undefined}
         >
           {tooltipContent}
         </Tooltip>
       )}
     >
-      <IconButton variant={variant} invertColors={invertColors} {...props} />
+      <IconButton {...props} />
     </OverlayTrigger>
   );
 }
 
 IconButtonWithTooltip.defaultProps = {
+  ...IconButton.defaultProps,
   tooltipPlacement: 'top',
-  variant: 'primary',
-  invertColors: false,
 };
 
 IconButtonWithTooltip.propTypes = {
@@ -144,7 +182,9 @@ IconButtonWithTooltip.propTypes = {
   invertColors: PropTypes.bool,
 };
 
-IconButton.IconButtonWithTooltip = IconButtonWithTooltip;
+(IconButton as any).IconButtonWithTooltip = IconButtonWithTooltip;
 
-export default IconButton;
+export default IconButton as typeof IconButton & {
+  IconButtonWithTooltip: typeof IconButtonWithTooltip,
+};
 export { IconButtonWithTooltip };

package/src/Modal/ModalPopup.jsx

@@ -34,6 +34,14 @@ function ModalPopup({
     },
   ];
 
+  const handleOnClickOutside = (e) => {
+    if (e.type === 'touchstart') {
+      return;
+    }
+
+    onClose();
+  };
+
   return (
     <ModalContextProvider onClose={onClose} isOpen={isOpen} isBlocking={isBlocking}>
       <RootComponent>
@@ -47,7 +55,7 @@ function ModalPopup({
             scrollLock={false}
             enabled={isOpen}
             onEscapeKey={onClose}
-            onClickOutside={onClose}
+            onClickOutside={handleOnClickOutside}
           >
             {isOpen && (
               <div className="pgn__modal-popup__tooltip">

package/src/Modal/_ModalDialog.scss

@@ -76,6 +76,10 @@
     border-top: solid 1px var(--pgn-color-light-base);
     padding-top: var(--pgn-spacing-modal-footer-padding-y);
   }
+
+  .pgn__modal-header {
+    border-radius: 0;
+  }
 }
 
 // Made specific due to a selector in Modal.scss

package/src/Modal/tests/ModalPopupNoMock.test.jsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { fireEvent, render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import ModalPopup from '../ModalPopup';
+
+describe('<ModalPopup />', () => {
+  const mockPositionRef = React.createRef();
+
+  describe('when isOpen', () => {
+    const isOpen = true;
+    const closeFn = jest.fn();
+
+    it('calls close on click events but not touchstart events', async () => {
+      render(
+        <ModalPopup
+          positionRef={mockPositionRef}
+          isOpen={isOpen}
+          onClose={closeFn}
+        >
+          <div>Modal Contents</div>
+        </ModalPopup>,
+      );
+      await fireEvent.touchStart(document.body);
+      expect(closeFn).not.toHaveBeenCalled();
+      await userEvent.click(document.body);
+      expect(closeFn).toHaveBeenCalled();
+    });
+  });
+});

package/src/Overlay/{index.jsx → index.tsx}

@@ -1,9 +1,14 @@
 import React from 'react';
-import BaseOverlay from 'react-bootstrap/Overlay';
-import BaseOverlayTrigger from 'react-bootstrap/OverlayTrigger';
+import BaseOverlay, { type OverlayProps, type Placement } from 'react-bootstrap/Overlay';
+import BaseOverlayTrigger, { type OverlayTriggerProps, type OverlayTriggerType } from 'react-bootstrap/OverlayTrigger';
+import Fade from 'react-bootstrap/Fade';
 import PropTypes from 'prop-types';
 
-const PLACEMENT_VARIANTS = [
+// Note: The only thing this file adds to the base component is propTypes validation.
+// As more Paragon consumers adopt TypeScript, we could consider removing almost all of this code
+// and just re-export the Overlay and OverlayTrigger components from react-bootstrap unmodified.
+
+const PLACEMENT_VARIANTS: Placement[] = [
   'auto-start',
   'auto',
   'auto-end',
@@ -21,16 +26,16 @@ const PLACEMENT_VARIANTS = [
   'left-start',
 ];
 
-const TRIGGER_VARIANTS = [
+const TRIGGER_VARIANTS: OverlayTriggerType[] = [
   'hover',
   'click',
   'focus',
 ];
 
-function Overlay(props) {
+function Overlay(props: OverlayProps) {
   return <BaseOverlay {...props} />;
 }
-function OverlayTrigger(props) {
+function OverlayTrigger(props: OverlayTriggerProps) {
   return (
     <BaseOverlayTrigger {...props}>
       {props.children}
@@ -88,7 +93,7 @@ Overlay.propTypes = {
    * Animate the entering and exiting of the Overlay. `true` will use the `<Fade>` transition,
    * or a custom react-transition-group `<Transition>` component can be provided.
    */
-  transition: PropTypes.oneOfType([PropTypes.bool, PropTypes.elementType]),
+  transition: PropTypes.oneOfType([PropTypes.object, PropTypes.bool]),
 };
 
 OverlayTrigger.propTypes = {
@@ -144,7 +149,7 @@ Overlay.defaultProps = {
   rootCloseEvent: undefined,
   show: false,
   target: undefined,
-  transition: true,
+  transition: Fade,
 };
 
 OverlayTrigger.defaultProps = {

package/src/Stepper/index.scss

@@ -8,8 +8,9 @@
 
   .pgn__stepper-header-step-list {
     list-style: none;
-    // stylelint-disable-next-line max-line-length
-    padding: var(--pgn-spacing-stepper-header-step-list-padding-y) var(--pgn-spacing-stepper-header-step-list-padding-x);
+    padding:
+      var(--pgn-spacing-stepper-header-step-list-padding-y)
+      var(--pgn-spacing-stepper-header-step-list-padding-x);
     display: flex;
     align-items: center;
     margin: var(--pgn-spacing-stepper-header-step-list-margin);

package/src/Tabs/index.scss

@@ -30,8 +30,9 @@
       margin: 0;
 
       .dropdown .dropdown-toggle {
-        // stylelint-disable-next-line max-line-length
-        padding: var(--pgn-spacing-tab-more-link-dropdown-toggle-padding-x) var(--pgn-spacing-tab-more-link-dropdown-toggle-padding-y);
+        padding:
+          var(--pgn-spacing-tab-more-link-dropdown-toggle-padding-x)
+          var(--pgn-spacing-tab-more-link-dropdown-toggle-padding-y);
 
         &:focus {
           background-color: var(--pgn-color-tab-more-link-dropdown-toggle-bg-focus);
@@ -62,8 +63,9 @@
   // Nav inverse pills
   &.nav-inverse-pills .pgn__tab_more.nav-link {
     .dropdown .dropdown-toggle {
-      // stylelint-disable-next-line max-line-length
-      padding: var(--pgn-spacing-tab-inverse-pills-link-dropdown-toggle-padding-x) var(--pgn-spacing-tab-inverse-pills-link-dropdown-toggle-padding-y);
+      padding:
+        var(--pgn-spacing-tab-inverse-pills-link-dropdown-toggle-padding-x)
+        var(--pgn-spacing-tab-inverse-pills-link-dropdown-toggle-padding-y);
       border: none;
 
       &:focus {
@@ -97,8 +99,9 @@
 
   // Nav inverse tabs
   &.nav-inverse-tabs .pgn__tab_more.nav-link .dropdown .dropdown-toggle {
-    // stylelint-disable-next-line max-line-length
-    padding: var(--pgn-spacing-tab-inverse-tabs-link-dropdown-toggle-padding-x) var(--pgn-spacing-tab-inverse-tabs-link-dropdown-toggle-padding-y);
+    padding:
+      var(--pgn-spacing-tab-inverse-tabs-link-dropdown-toggle-padding-x)
+      var(--pgn-spacing-tab-inverse-tabs-link-dropdown-toggle-padding-y);
 
     &:hover {
       background-color: var(--pgn-color-tab-inverse-pills-link-dropdown-toggle-bg-hover);

package/src/Tooltip/{index.jsx → index.tsx}

@@ -1,9 +1,15 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
-import BaseTooltip from 'react-bootstrap/Tooltip';
+import BaseTooltip, { type TooltipProps as BaseTooltipProps } from 'react-bootstrap/Tooltip';
+import { type Placement } from 'react-bootstrap/Overlay';
+import type { ComponentWithAsProp } from '../utils/types/bootstrap';
 
-const PLACEMENT_VARIANTS = [
+interface TooltipProps extends BaseTooltipProps {
+  variant?: 'light';
+}
+
+const PLACEMENT_VARIANTS: Placement[] = [
   'auto-start',
   'auto',
   'auto-end',
@@ -21,7 +27,7 @@ const PLACEMENT_VARIANTS = [
   'left-start',
 ];
 
-const Tooltip = React.forwardRef(({
+const Tooltip: ComponentWithAsProp<'div', TooltipProps> = React.forwardRef(({
   children,
   variant,
   ...props