@openedx/paragon 22.0.0-alpha.23 → 22.0.0

package/src/ListBox/index.jsx

@@ -0,0 +1,115 @@
+/* eslint-disable max-len */
+import classNames from 'classnames';
+import PropTypes from 'prop-types';
+import React from 'react';
+import { nonNegativeInteger } from '../utils/propTypes';
+
+export default class ListBox extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.onFocus = this.onFocus.bind(this);
+    this.onKeyDown = this.onKeyDown.bind(this);
+
+    this.state = {
+      selectedOptionIndex: null,
+    };
+  }
+
+  static getDerivedStateFromProps(nextProps, prevState) {
+    const { selectedOptionIndex } = nextProps;
+
+    if (selectedOptionIndex !== prevState.selectedOptionIndex
+      && selectedOptionIndex !== undefined) {
+      return { selectedOptionIndex };
+    }
+
+    return null;
+  }
+
+  onFocus() {
+    // if no ListBoxOption is selected, select first ListBoxOption on ListBox focus
+    if (!this.state.selectedOptionIndex) {
+      this.setState({
+        selectedOptionIndex: 0,
+      });
+    }
+  }
+
+  onKeyDown(e) {
+    switch (e.key) {
+      case 'ArrowDown': {
+        // prevent scrolling entire modal body with arrow keys
+        e.preventDefault();
+        if (this.state.selectedOptionIndex < React.Children.count(this.props.children) - 1) {
+          this.setState(state => ({
+            selectedOptionIndex: state.selectedOptionIndex + 1,
+          }));
+        }
+        break;
+      }
+      case 'ArrowUp': {
+        // prevent scrolling entire modal body with arrow keys
+        e.preventDefault();
+
+        if (this.state.selectedOptionIndex > 0) {
+          this.setState(state => ({
+            selectedOptionIndex: state.selectedOptionIndex - 1,
+          }));
+        }
+        break;
+      }
+      default:
+    }
+  }
+
+  renderChildren() {
+    return React.Children.map(this.props.children, (child, index) => React.cloneElement(child, {
+      index,
+      isSelected: index === this.state.selectedOptionIndex,
+      onSelect: () => { this.setState({ selectedOptionIndex: index }); child.props.onSelect(); },
+    }));
+  }
+
+  render() {
+    const {
+      children,
+      className,
+      selectedOptionIndex,
+      tag,
+      ...other
+    } = this.props;
+
+    return React.createElement(
+      this.props.tag,
+      {
+        'aria-activedescendant': this.state.selectedOptionIndex === null ? null : `list-box-option-${this.state.selectedOptionIndex}`,
+        className: classNames(['list-group', this.props.className]),
+        onFocus: this.onFocus,
+        onKeyDown: this.onKeyDown,
+        role: 'listbox',
+        tabIndex: 0,
+        ...other,
+      },
+      this.renderChildren(),
+    );
+  }
+}
+
+ListBox.propTypes = {
+  /** specifies the ListBoxOption component(s) that will be displayed within the ListBox element. You can pass in one or more ListBoxOption components.
+ */
+  children: PropTypes.node.isRequired,
+  /** specifies Bootstrap class names to apply to the ListBox component. The default is an empty string. */
+  className: PropTypes.string,
+  /** Although the ListBox component keeps track of which ListBoxOption is selected, `selectedOptionIndex` provides a mechanism for an override, if necessary. An example would be to clear the selectedOption when moving between views. Note that override is not permanent and that clicking on a ListBoxOption or interacting with the ListBox with the keyboard will change the selected ListBoxOption relative to the original override. The default is undefined. */
+  selectedOptionIndex: nonNegativeInteger,
+  /** used to specify the element type of the rendered ListBox component. The default is div. Example alternatives include ol, ul, span, etc. */
+  tag: PropTypes.string,
+};
+
+ListBox.defaultProps = {
+  className: undefined,
+  selectedOptionIndex: undefined,
+  tag: 'div',
+};

package/src/ListBoxOption/ListBoxOption.test.jsx

@@ -0,0 +1,154 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import ListBoxOption from '.';
+
+describe('ListBoxOption', () => {
+  const listBoxOptionChild = 'test';
+
+  describe('rendering', () => {
+    it('should have false aria-selected attribute by default', () => {
+      render(
+        <ListBoxOption data-testid="listbox-option">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement.getAttribute('aria-selected')).toEqual('false');
+    });
+
+    it('should have false aria-selected attribute when isSelected prop is false', () => {
+      const { rerender } = render(
+        <ListBoxOption data-testid="listbox-option" isSelected={false}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement.getAttribute('aria-selected')).toEqual('false');
+
+      rerender(
+        <ListBoxOption isSelected>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      expect(listBoxOptionElement.getAttribute('aria-selected')).toEqual('true');
+    });
+
+    it('should render a div by default', () => {
+      const { container } = render(
+        <ListBoxOption>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = container.querySelector('div');
+      expect(listBoxOptionElement).toBeInTheDocument();
+    });
+
+    it('should render an HTML element when tag prop is an HTML element', () => {
+      const { container } = render(
+        <ListBoxOption tag="li">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = container.querySelector('li');
+      expect(listBoxOptionElement).toBeInTheDocument();
+    });
+
+    it('should have correct default classNames', () => {
+      render(
+        <ListBoxOption data-testid="listbox-option">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement).toHaveClass('list-group-item');
+      expect(listBoxOptionElement).toHaveClass('list-group-item-action');
+    });
+
+    it('should not have active className by default', () => {
+      render(
+        <ListBoxOption data-testid="listbox-option">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement).not.toHaveClass('active');
+    });
+
+    it('should have correct default id', () => {
+      render(
+        <ListBoxOption data-testid="listbox-option">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement.getAttribute('id')).toBeNull();
+    });
+
+    it('should have correct id when index prop is a number', () => {
+      const { rerender } = render(
+        <ListBoxOption data-testid="listbox-option" index={1}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement.getAttribute('id')).toEqual('list-box-option-1');
+
+      rerender(
+        <ListBoxOption index={2}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      expect(listBoxOptionElement.getAttribute('id')).toEqual('list-box-option-2');
+    });
+
+    it('should have option role', () => {
+      render(
+        <ListBoxOption data-testid="listbox-option">{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement.getAttribute('role')).toEqual('option');
+    });
+
+    it('should have active className when isSelected prop is true', () => {
+      const { rerender } = render(
+        <ListBoxOption data-testid="listbox-option" isSelected={false}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+      expect(listBoxOptionElement).not.toHaveClass('active');
+
+      rerender(
+        <ListBoxOption isSelected>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      expect(listBoxOptionElement).toHaveClass('active');
+    });
+  });
+
+  describe('behavior', () => {
+    it('should call onSelect on mouse down', async () => {
+      const onSelectSpy = jest.fn();
+      render(
+        <ListBoxOption data-testid="listbox-option" onSelect={onSelectSpy}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+
+      await userEvent.click(listBoxOptionElement);
+
+      expect(onSelectSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call onSelect when receiving new isSelected prop', async () => {
+      const onSelectSpy = jest.fn();
+      const { rerender } = render(
+        <ListBoxOption data-testid="listbox-option" onSelect={onSelectSpy}>{listBoxOptionChild}</ListBoxOption>,
+      );
+
+      const listBoxOptionElement = screen.getByTestId('listbox-option');
+
+      await userEvent.click(listBoxOptionElement);
+
+      rerender(
+        <ListBoxOption onSelect={onSelectSpy} isSelected>
+          {listBoxOptionChild}
+        </ListBoxOption>,
+      );
+
+      expect(onSelectSpy).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/ListBoxOption/index.jsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import classNames from 'classnames';
+import PropTypes from 'prop-types';
+
+export default class ListBoxOption extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.onMouseDown = this.onMouseDown.bind(this);
+  }
+
+  componentDidUpdate(prevProps) {
+    if (this.props.isSelected && !prevProps.isSelected) {
+      this.props.onSelect();
+    }
+  }
+
+  /**
+   * onMouseDown is used instead of onClick because onClick triggers the focus
+   * event before click event. This focus event bubbles up to the parent
+   * (since onFocus bubbles in React), which triggers the ListBox's onFocus function.
+   * This function will select the first ListBoxOption if one is not selected, and this
+   * causes the user to see the first option selected before their desired option is selected
+   * when the click event is fired shortly thereafter. The mouseDown event occurs before the
+   * focus event, which prevents this behavior.
+   */
+  onMouseDown() {
+    this.props.onSelect();
+  }
+
+  render() {
+    const {
+      children,
+      className,
+      index,
+      isSelected,
+      tag,
+      ...other
+    } = this.props;
+
+    return React.createElement(
+      this.props.tag,
+      {
+        'aria-selected': isSelected,
+        className: classNames(
+          'list-group-item',
+          'list-group-item-action',
+          {
+            active: this.props.isSelected,
+          },
+          className,
+        ),
+        id: index === undefined ? null : `list-box-option-${index}`,
+        onMouseDown: this.onMouseDown,
+        role: 'option',
+        ...other,
+      },
+      children,
+    );
+  }
+}
+
+ListBoxOption.propTypes = {
+  children: PropTypes.node.isRequired,
+  className: PropTypes.string,
+  index: PropTypes.number,
+  isSelected: PropTypes.bool,
+  tag: PropTypes.string,
+  onSelect: PropTypes.func,
+};
+
+ListBoxOption.defaultProps = {
+  className: undefined,
+  index: undefined,
+  isSelected: false,
+  tag: 'div',
+  onSelect: () => { },
+};

package/src/Menu/MenuItem.jsx

@@ -40,9 +40,9 @@ MenuItem.propTypes = {
   /** Specifies the base element */
   as: PropTypes.elementType,
   /** Specifies the jsx before the content of the ``MenuItem`` */
-  iconBefore: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  iconBefore: PropTypes.oneOfType([PropTypes.element, PropTypes.elementType]),
   /** Specifies the jsx after the content of the ``MenuItem`` */
-  iconAfter: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  iconAfter: PropTypes.oneOfType([PropTypes.element, PropTypes.elementType]),
 };
 
 MenuItem.defaultProps = {

package/src/Menu/_variables.scss

@@ -0,0 +1,24 @@
+$menu-box-shadow:                                $box-shadow !default;
+$menu-border-radius:                             .25em !default;
+$menu-bg:                                        $white !default;
+$menu-max-height:                                16.813rem !default;
+$menu-item-height:                               3rem !default;
+$menu-item-width:                                19rem !default;
+$menu-item-width-xs:                             13.438rem !default;
+$menu-item-color:                                $body-color !default;
+$menu-item-bg:                                   transparent !default;
+$menu-item-border-color:                         $menu-item-bg !default;
+$menu-item-border-width:                         $btn-border-width !default;
+$menu-item-hover-border:                         $menu-item-bg !default;
+$menu-item-padding-x:                            $btn-padding-x !default;
+$menu-item-padding-y:                            $btn-padding-y !default;
+$menu-item-hover-color:                          $btn-tertiary-color !default;
+$menu-item-hover-border-color:                   $menu-item-bg !default;
+$menu-item-hover-bg:                             $btn-tertiary-hover-bg !default;
+$menu-item-icon-margin-left:                     .25em !default;
+$menu-item-icon-margin-right:                    $menu-item-icon-margin-left !default;
+$menu-item-focus-bg:                             $btn-tertiary-active-bg !default;
+$menu-item-border:                               $menu-item-border-width solid $menu-item-border-color !default;
+$menu-select-btn-link-color:                     $primary-500 !default;
+$menu-select-btn-link-text-decoration-line:      underline !default;
+$menu-select-btn-link-text-decoration-thickness: .125rem !default;

package/src/Menu/index.scss

@@ -1,26 +1,28 @@
+@import "variables";
+
 .pgn__menu {
-  border-radius: var(--pgn-size-menu-base-border-radius);
-  box-shadow: var(--pgn-elevation-menu-box-shadow);
-  background-color: var(--pgn-color-menu-bg);
+  border-radius: $menu-border-radius;
+  box-shadow: $menu-box-shadow;
+  background-color: $menu-bg;
   overflow: auto;
-  max-height: var(--pgn-size-menu-base-max-height);
+  max-height: $menu-max-height;
 
   .pgn__menu-item {
     display: flex;
     align-items: center;
     justify-content: flex-start;
-    width: var(--pgn-size-menu-item-width-base);
-    color: var(--pgn-color-menu-item-color);
+    width: $menu-item-width;
+    color: $menu-item-color;
     text-align: center;
     vertical-align: middle;
     user-select: none;
-    background-color: var(--pgn-color-menu-item-bg);
-    border: var(--pgn-size-menu-item-border-width) solid var(--pgn-color-menu-item-border);
-    padding: var(--pgn-spacing-menu-item-padding-y) var(--pgn-spacing-menu-item-padding-x);
-    height: var(--pgn-size-menu-item-height);
+    background-color: $menu-item-bg;
+    border: $menu-item-border;
+    padding: $menu-item-padding-y $menu-item-padding-x;
+    height: $menu-item-height;
 
-    @media (max-width: var(--pgn-size-container-max-width-xs)) {
-      width: var(--pgn-size-menu-item-width-xs);
+    @media (max-width: $max-width-xs) {
+      width: $menu-item-width-xs;
     }
 
     .pgn__menu-item-text {
@@ -36,40 +38,40 @@
 
     @include hover {
       text-decoration: none;
-      color: var(--pgn-color-menu-item-hover-color);
-      border-color: var(--pgn-color-menu-item-hover-border);
-      background: var(--pgn-color-menu-item-hover-bg);
+      color: $menu-item-hover-color;
+      border-color: $menu-item-hover-border-color;
+      background: $menu-item-hover-bg;
     }
 
     // Disabled comes first so active can properly restyle
     &.disabled,
     &:disabled {
-      opacity: var(--pgn-other-btn-disabled-opacity);
+      opacity: $btn-disabled-opacity;
     }
 
     &.focus,
     &:focus {
-      font-weight: var(--pgn-typography-font-weight-bolder);
-      background-color: var(--pgn-color-menu-item-focus-bg);
+      font-weight: $font-weight-bolder;
+      background-color: $menu-item-focus-bg;
     }
 
     .btn-icon-before {
       margin-inline-end: .5rem;
-      margin-left: calc(var(--pgn-spacing-menu-item-icon-margin-left) * -1);
+      margin-left: calc(#{$menu-item-icon-margin-left} * -1);
 
       [dir="rtl"] & {
-        margin-right: calc(var(--pgn-spacing-menu-item-icon-margin-right) * -1);
+        margin-right: calc(#{$menu-item-icon-margin-right} * -1);
         margin-left: .5rem;
       }
     }
 
     .btn-icon-after {
       margin-inline-start: .5rem;
-      margin-right: calc(var(--pgn-spacing-menu-item-icon-margin-right) * -1);
+      margin-right: calc(#{$menu-item-icon-margin-right} * -1);
 
       [dir="rtl"] & {
         margin-right: .5rem;
-        margin-left: calc(var(--pgn-spacing-menu-item-icon-margin-left) * -1);
+        margin-left: calc(#{$menu-item-icon-margin-left} * -1);
       }
     }
   }
@@ -77,12 +79,12 @@
 
 .pgn__menu-select {
   .btn.btn-link {
-    color: var(--pgn-color-menu-select-btn-link-color);
+    color: $menu-select-btn-link-color;
 
     &:hover,
     &:focus {
-      text-decoration-line: var(--pgn-typography-menu-select-btn-link-text-decoration-line);
-      text-decoration-thickness: var(--pgn-typography-menu-select-btn-link-text-decoration-thickness);
+      text-decoration-line: $menu-select-btn-link-text-decoration-line;
+      text-decoration-thickness: $menu-select-btn-link-text-decoration-thickness;
     }
   }
 

package/src/Modal/ModalDialog.jsx

@@ -116,6 +116,9 @@ ModalDialog.propTypes = {
    * Prevent clicking on the backdrop to close the modal
    */
   isBlocking: PropTypes.bool,
+  /**
+   * Specifies the z-index of the modal
+   */
   zIndex: PropTypes.number,
 };
 

package/src/Modal/README.md

@@ -0,0 +1,148 @@
+---
+title: 'Modal'
+type: 'component'
+components:
+- Modal
+categories:
+- Overlays
+status: 'Deprecate soon'
+designStatus: 'Done'
+devStatus: 'To Do'
+notes: |
+  Replaced by ModalDialog.
+---
+
+## Example Usage
+
+```jsx live
+class ModalWrapper extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.openModal = this.openModal.bind(this);
+    this.resetModalWrapperState = this.resetModalWrapperState.bind(this);
+
+    this.state = { open: false };
+  }
+
+  openModal() {
+    this.setState({ open: true });
+  }
+
+  resetModalWrapperState() {
+    this.setState({ open: false });
+  }
+
+  render() {
+    return (
+      <div>
+        <Modal
+          open={this.state.open}
+          title="Modal title."
+          body={
+            <div>
+              <p>Enter your e-mail address to receive free cat facts!</p>
+              <InputText
+                name="e-mail"
+                label="E-Mail Address"
+              />
+            </div>
+          }
+          parentSelector={this.props.parentSelector}
+          onClose={this.resetModalWrapperState}
+          buttons={[
+            <Button variant="success" data-autofocus>Green button!</Button>
+          ]}
+        />
+        <Button
+          onClick={this.openModal}
+          variant="light"
+        >
+          Click me to open a modal!
+        </Button>
+      </div>
+    );
+  }
+}
+```
+
+## configurable buttons
+
+```jsx
+<Modal
+  open
+  title="Modal title."
+  body="Modal body."
+  buttons={[
+    <Button variant="primary">Blue button!</Button>,
+    {
+      label: 'Red button!',
+      buttonType: 'danger',
+    },
+    <Button variant="success">Green button!</Button>,
+  ]}
+  onClose={() => {}}
+/>
+```
+
+## configurable title and body
+
+```jsx
+<Modal
+  open
+  title="Custom title!"
+  body="Custom body!"
+  buttons={[
+    <Button variant="dark">Dark button!</Button>
+  ]}
+  onClose={() => {}}
+/>
+```
+
+## configurable buttons that perform actions
+
+```jsx
+<Modal
+  open
+  title="Modal title."
+  body="Modal body."
+  buttons={[
+    <Button
+      variant="light"
+      onClick={action('button-click')}
+    >
+      Click me and check the console!
+    </Button>,
+  ]}
+  onClose={() => {}}
+/>
+```
+
+## configurable close button string
+
+```jsx
+<Modal
+  open
+  title="Modal title."
+  body="Modal body."
+  closeText="SHOO!"
+  onClose={() => {}}
+/>
+```
+
+## configurable close button element
+
+```jsx
+<Modal
+  open
+  title="Modal title."
+  body="Modal body."
+  closeText={
+    <Icon
+      className="fa fa-ship"
+      screenReaderText="Close"
+    />
+  }
+  onClose={() => {}}
+/>
+```