@openedx/paragon 23.0.0-alpha.2 → 23.0.0-alpha.4

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.scss

@@ -1,5 +1,151 @@
 @import "mixins";
 
+:root {
+  --pgn-elevation-icon-button-box-shadow-primary-base:
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-primary-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-primary-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-primary-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-secondary-base:
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-secondary-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-secondary-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-brand-base:
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-brand-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-brand-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-brand-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-success-base:
+    var(--pgn-elevation-icon-button-box-shadow-success-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-success-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-success-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-success-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-success-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-success-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-success-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-success-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-warning-base:
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-warning-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-warning-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-warning-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-danger-base:
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-danger-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-danger-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-danger-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-light-base:
+    var(--pgn-elevation-icon-button-box-shadow-light-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-light-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-light-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-light-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-light-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-light-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-light-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-light-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-dark-base:
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-dark-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-dark-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse)
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-dark-inverse-color);
+
+  --pgn-elevation-icon-button-box-shadow-black-base:
+    var(--pgn-elevation-icon-button-box-shadow-black-base-inset)
+    var(--pgn-elevation-icon-button-box-shadow-black-base-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-black-base-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-black-base-blur)
+    var(--pgn-elevation-icon-button-box-shadow-black-base-spread)
+    var(--pgn-elevation-icon-button-box-shadow-black-base-color);
+
+  --pgn-elevation-icon-button-box-shadow-black-inverse:
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-inset)
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-offset-x)
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-offset-y)
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-blur)
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-spread)
+    var(--pgn-elevation-icon-button-box-shadow-black-inverse-color);
+}
+
 .btn-icon {
   @include btn-icon-size(var(--pgn-size-icon-button-diameter-md));
 

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/Menu/index.scss

@@ -1,3 +1,11 @@
+:root {
+  --pgn-elevation-menu-box-shadow:
+    var(--pgn-elevation-menu-box-shadow-offset-x)
+    var(--pgn-elevation-menu-box-shadow-offset-y)
+    var(--pgn-elevation-menu-box-shadow-blur)
+    var(--pgn-elevation-menu-box-shadow-color);
+}
+
 .pgn__menu {
   border-radius: var(--pgn-size-menu-base-border-radius);
   box-shadow: var(--pgn-elevation-menu-box-shadow);

package/src/Modal/ModalDialog.jsx

@@ -122,8 +122,13 @@ ModalDialog.propTypes = {
    * Specifies the z-index of the modal
    */
   zIndex: PropTypes.number,
-  /** Specifies whether overflow is visible in the modal */
-  isOverflowVisible: PropTypes.bool,
+  /**
+   * Specifies whether overflow content inside the modal should be visible.
+   * - `true` - content that exceeds the modal boundaries will remain visible outside the modal's main viewport,
+   * rather than being clipped or hidden.
+   * - `false` - any overflow content will be clipped to fit within the modal's dimensions.
+   */
+  isOverflowVisible: PropTypes.bool.isRequired,
 };
 
 ModalDialog.defaultProps = {
@@ -137,7 +142,6 @@ ModalDialog.defaultProps = {
   isFullscreenOnMobile: false,
   isBlocking: false,
   zIndex: undefined,
-  isOverflowVisible: true,
 };
 
 ModalDialog.Header = ModalDialogHeader;

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

@@ -1,3 +1,23 @@
+:root {
+  --pgn-elevation-modal-content-box-shadow-sm-up:
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-1-offset-x)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-1-offset-y)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-1-blur)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-1-color),
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-2-offset-x)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-2-offset-y)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-2-blur)
+    var(--pgn-elevation-modal-content-box-shadow-sm-up-2-color);
+
+  --pgn-spacing-modal-footer-padding-base:
+    var(--pgn-spacing-modal-footer-padding-base-y)
+    var(--pgn-spacing-modal-footer-padding-base-x);
+
+  --pgn-spacing-modal-header-padding-base:
+    var(--pgn-spacing-modal-header-padding-base-y)
+    var(--pgn-spacing-modal-header-padding-base-x);
+}
+
 .pgn__modal {
   background: var(--pgn-color-modal-content-bg);
   border-radius: calc(var(--pgn-size-modal-content-border-radius) - var(--pgn-size-modal-content-border-width));
@@ -76,6 +96,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
@@ -118,7 +142,7 @@
   }
 
   .pgn__modal-title {
-    font-size: var(--pgn-typography-font-size-h3);
+    font-size: var(--pgn-typography-font-size-h3-base);
     margin-inline-end: 3rem; // roughly accomodate the width of the close buttonn
     text-align: start;
   }
@@ -306,7 +330,7 @@
   }
 
   .pgn__modal-title {
-    font-size: var(--pgn-typography-font-size-h4);
+    font-size: var(--pgn-typography-font-size-h4-base);
     display: flex;
     flex-grow: 1;
     align-items: center;