@openedx/paragon 22.0.0-alpha.23 → 22.0.0

package/src/CheckBox/CheckBox.test.jsx

@@ -0,0 +1,65 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import CheckBox from '.';
+
+describe('<CheckBox />', () => {
+  it('attributes are set correctly', () => {
+    render(<CheckBox name="checkbox" label="check me out!" />);
+    const checkbox = screen.getByLabelText('check me out!');
+    expect(checkbox).toBeInTheDocument();
+    expect(checkbox).toHaveAttribute('type', 'checkbox');
+    expect(checkbox).not.toBeChecked();
+    expect(checkbox).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('aria-label changes after click', async () => {
+    render(<CheckBox name="checkbox" label="check me out!" />);
+    const checkbox = screen.getByLabelText('check me out!');
+    expect(checkbox).toHaveAttribute('aria-checked', 'false');
+    await userEvent.click(checkbox);
+    expect(checkbox).toHaveAttribute('aria-checked', 'true');
+    await userEvent.click(checkbox);
+    expect(checkbox).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('check that callback function is triggered when clicked', async () => {
+    const onChangeSpy = jest.fn();
+    render(<CheckBox name="checkbox" label="check me out!" onChange={onChangeSpy} />);
+    const checkbox = screen.getByLabelText('check me out!');
+    expect(onChangeSpy).toHaveBeenCalledTimes(0);
+    await userEvent.click(checkbox);
+    expect(onChangeSpy).toHaveBeenCalledTimes(1);
+    expect(onChangeSpy).toHaveBeenCalledWith(true, 'checkbox');
+    await userEvent.click(checkbox);
+    expect(onChangeSpy).toHaveBeenCalledTimes(2);
+    expect(onChangeSpy).toHaveBeenCalledWith(false, 'checkbox');
+  });
+
+  it('checks if start state can be set to checked', async () => {
+    render(<CheckBox name="checkbox" label="I start checked" checked />);
+    const checkbox = screen.getByLabelText('I start checked');
+    expect(checkbox).toBeChecked();
+    expect(checkbox).toHaveAttribute('aria-checked', 'true');
+    await userEvent.click(checkbox);
+    expect(checkbox).not.toBeChecked();
+    expect(checkbox).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('checkbox can be disabled', async () => {
+    render(<CheckBox name="checkbox" label="I am disabled" disabled />);
+    const checkbox = screen.getByLabelText('I am disabled');
+    expect(checkbox).toBeDisabled();
+    await userEvent.click(checkbox);
+    expect(checkbox).toBeDisabled();
+  });
+
+  it('overrides state value when props value changes', () => {
+    const { rerender } = render(<CheckBox name="checkbox" label="I start checked" checked />);
+    const checkbox = screen.getByLabelText('I start checked');
+    expect(checkbox).toBeChecked();
+    rerender(<CheckBox name="checkbox" label="I start checked" checked={false} />);
+    expect(checkbox).not.toBeChecked();
+  });
+});

package/src/CheckBox/README.md

@@ -0,0 +1,93 @@
+---
+title: 'Checkbox'
+type: 'component'
+components:
+- Check
+categories:
+- Forms (deprecated)
+status: 'Deprecate Soon'
+designStatus: 'TBD'
+devStatus: 'Done'
+notes: |
+  Replaced by Form.Checkbox
+---
+
+## Basic usage
+
+```jsx live
+<CheckBox
+  name="checkbox"
+  label="check me out!"
+/>
+```
+
+## Disabled
+
+```jsx live
+<CheckBox
+  name="checkbox"
+  label="you cannot check me out"
+  disabled
+/>
+```
+
+## Default checked
+
+```jsx live
+<CheckBox
+  name="checkbox"
+  label="(un)check me out"
+  checked
+/>
+```
+
+## Call a function
+
+```jsx live
+<CheckBox
+  name="checkbox"
+  label="check out the console"
+  onChange={() => console.log('the checkbox changed state')}
+/>
+```
+
+## Controlled example
+
+```jsx live
+class CheckBoxWrapper extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.toggleCheckBox = this.toggleCheckBox.bind(this);
+
+    this.state = {
+      checked: false,
+    };
+  }
+
+  toggleCheckBox() {
+    this.setState({
+      checked: !this.state.checked,
+    });
+  }
+
+  render() {
+    return (
+      <div className="d-flex align-items-center">
+        <Button
+          variant="light"
+          className="mr-3"
+          onClick={this.toggleCheckBox}
+        >
+          Click me to toggle the check box!
+        </Button>
+        <CheckBox
+          name="checkbox"
+          label="click the button"
+          checked={this.state.checked}
+        />
+      </div>
+    );
+  }
+}
+```

package/src/CheckBox/index.jsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+import asInput from '../asInput';
+import withDeprecatedProps, { DeprTypes } from '../withDeprecatedProps';
+
+class Check extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.onChange = this.onChange.bind(this);
+
+    this.state = {
+      checked: props.checked || false,
+    };
+  }
+
+  /* eslint-disable react/no-did-update-set-state */
+  componentDidUpdate(prevProps) {
+    if (prevProps.checked !== this.props.checked) {
+      this.setState({
+        checked: this.props.checked,
+      });
+    }
+  }
+
+  onChange(event) {
+    this.setState(prevState => ({
+      checked: !prevState.checked,
+    }));
+    this.props.onChange(event);
+  }
+
+  render() {
+    const {
+      inputRef,
+      ...others
+    } = this.props;
+    return (
+      <input
+        {...others}
+        type="checkbox"
+        ref={inputRef}
+        checked={this.state.checked}
+        aria-checked={this.state.checked}
+        onChange={this.onChange}
+      />
+    );
+  }
+}
+
+Check.propTypes = {
+  // eslint-disable-next-line max-len
+  /** (`Boolean`): `true` if the state should be checked, `false` otherwise. This prop can be used to manage the Checkbox more directly, overriding the default Checkbox checked state. */
+  checked: PropTypes.bool,
+  /** (`Boolean`): `true` if the checkbox should be disabled, `false` otherwise */
+  onChange: PropTypes.func,
+  /** function to be called when the checkbox changes state */
+  inputRef: PropTypes.oneOfType([
+    PropTypes.func,
+    PropTypes.shape({ current: PropTypes.instanceOf(PropTypes.element) }),
+  ]),
+};
+
+Check.defaultProps = {
+  checked: false,
+  onChange: () => {},
+  inputRef: undefined,
+};
+
+const CheckBox = asInput(withDeprecatedProps(Check, 'Checkbox', {
+  className: {
+    deprType: DeprTypes.FORMAT,
+    expect: value => typeof value === 'string',
+    transform: value => (Array.isArray(value) ? value.join(' ') : value),
+    message: 'It should be a string.',
+  },
+}), 'checkbox', false);
+
+export default CheckBox;

package/src/CheckBoxGroup/CheckBoxGroup.test.jsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import CheckBoxGroup from '.';
+import CheckBox from '../CheckBox';
+
+describe('<CheckBoxGroup />', () => {
+  it('correct number of children displayed in group', () => {
+    const checkBoxGroup = (
+      <CheckBoxGroup>
+        <CheckBox
+          id="checkbox1"
+          name="basicCheckBox"
+          label="CheckBox 1"
+        />
+        <CheckBox
+          id="checkbox2"
+          name="basicCheckBox"
+          label="CheckBox 2"
+        />
+        <CheckBox
+          id="checkbox3"
+          name="basicCheckBox"
+          label="CheckBox 3"
+        />
+      </CheckBoxGroup>
+    );
+    const { getByLabelText } = render(checkBoxGroup);
+
+    expect(getByLabelText('CheckBox 1')).toBeInTheDocument();
+    expect(getByLabelText('CheckBox 2')).toBeInTheDocument();
+    expect(getByLabelText('CheckBox 3')).toBeInTheDocument();
+  });
+});

package/src/CheckBoxGroup/README.md

@@ -0,0 +1,35 @@
+---
+title: 'CheckBoxGroup'
+type: 'component'
+components:
+- CheckBoxGroup
+categories:
+- Forms (deprecated)
+status: 'Deprecate Soon'
+designStatus: 'To Do'
+devStatus: 'To Do'
+notes: |
+  Replaced by Form.Checkbox and Form.CheckboxSet
+---
+
+## Basic Usage
+
+```jsx live
+<CheckBoxGroup>
+  <CheckBox
+    id="checkbox1"
+    name="basicCheckBox1"
+    label="CheckBox 1"
+  />
+  <CheckBox
+    id="checkbox2"
+    name="basicCheckBox2"
+    label="CheckBox 2"
+  />
+  <CheckBox
+    id="checkbox3"
+    name="basicCheckBox3"
+    label="CheckBox 3"
+  />
+</CheckBoxGroup>
+```

package/src/CheckBoxGroup/index.jsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+function CheckBoxGroup(props) {
+  return (
+    <div className="form-group">
+      {props.children}
+    </div>
+  );
+}
+
+CheckBoxGroup.propTypes = {
+  // eslint-disable-next-line max-len
+  /** represents the CheckBox components defined within the CheckBoxGroup component and is not a specific named prop that needs to be passed in. At least one CheckBox must be defined within the group. Example: `<CheckBoxGroup><CheckBox .../></CheckBoxGroup>`
+   */
+  children: PropTypes.arrayOf(PropTypes.element).isRequired,
+};
+
+export default CheckBoxGroup;

package/src/Chip/Chip.test.jsx

@@ -4,6 +4,7 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 import { Close } from '../../icons';
+import { STYLE_VARIANTS } from './constants';
 import Chip from '.';
 
 function TestChip(props) {
@@ -24,58 +25,123 @@ describe('<Chip />', () => {
     });
     it('renders with props iconBefore', () => {
       const tree = renderer.create((
-        <TestChip iconBefore={Close} />
+        <TestChip iconBefore={Close} iconBeforeAlt="close icon" />
       )).toJSON();
       expect(tree).toMatchSnapshot();
     });
     it('renders with props iconAfter', () => {
       const tree = renderer.create((
-        <TestChip iconAfter={Close} />
+        <TestChip iconAfter={Close} iconAfterAlt="close icon" />
       )).toJSON();
       expect(tree).toMatchSnapshot();
     });
     it('renders with props iconBefore and iconAfter', () => {
       const tree = renderer.create((
-        <TestChip iconBefore={Close} iconAfter={Close}>Chip</TestChip>
+        <TestChip
+          iconBefore={Close}
+          iconBeforeAlt="close icon"
+          iconAfter={Close}
+          iconAfterAlt="close icon"
+        >
+          Chip
+        </TestChip>
+      )).toJSON();
+      expect(tree).toMatchSnapshot();
+    });
+    it('renders div with "button" role when onClick is provided', () => {
+      const tree = renderer.create((
+        <TestChip onClick={jest.fn}>Chip</TestChip>
       )).toJSON();
       expect(tree).toMatchSnapshot();
     });
   });
 
   describe('correct rendering', () => {
+    it('render a non-interactive element if onClick handlers are not provided', () => {
+      render(<TestChip />);
+      expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    });
+    it('render an interactive element if onClick handler is provided', () => {
+      render(<TestChip onClick={jest.fn} />);
+      expect(screen.queryByRole('button')).toBeInTheDocument();
+    });
     it('renders with correct class when variant is added', () => {
-      render(<TestChip variant="dark" data-testid="chip" />);
-      const chip = screen.getByTestId('chip');
+      render(<TestChip variant={STYLE_VARIANTS.DARK} onClick={jest.fn} />);
+      const chip = screen.getByRole('button');
       expect(chip).toHaveClass('pgn__chip pgn__chip-dark');
     });
     it('renders with active class when disabled prop is added', () => {
-      render(<TestChip disabled data-testid="chip" />);
-      const chip = screen.getByTestId('chip');
+      render(<TestChip disabled onClick={jest.fn} />);
+      const chip = screen.getByRole('button');
       expect(chip).toHaveClass('disabled');
     });
     it('renders with the client\'s className', () => {
       const className = 'testClassName';
-      render(<TestChip className={className} data-testid="chip" />);
-      const chip = screen.getByTestId('chip');
+      render(<TestChip className={className} onClick={jest.fn} />);
+      const chip = screen.getByRole('button');
       expect(chip).toHaveClass(className);
     });
     it('onIconAfterClick is triggered', async () => {
       const func = jest.fn();
       render(
-        <TestChip iconAfter={Close} onIconAfterClick={func} />,
+        <TestChip
+          iconAfter={Close}
+          onIconAfterClick={func}
+          iconAfterAlt="icon-after"
+        />,
       );
-      const iconAfter = screen.getByTestId('icon-after');
+      const iconAfter = screen.getByLabelText('icon-after');
       await userEvent.click(iconAfter);
-      expect(func).toHaveBeenCalled();
+      expect(func).toHaveBeenCalledTimes(1);
     });
     it('onIconAfterKeyDown is triggered', async () => {
       const func = jest.fn();
       render(
-        <TestChip iconAfter={Close} onIconAfterClick={func} />,
+        <TestChip
+          iconAfter={Close}
+          onIconAfterClick={func}
+          iconAfterAlt="icon-after"
+        />,
+      );
+      const iconAfter = screen.getByLabelText('icon-after');
+      await userEvent.click(iconAfter, '{enter}', { skipClick: true });
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+    it('onIconBeforeClick is triggered', async () => {
+      const func = jest.fn();
+      render(
+        <TestChip
+          iconBefore={Close}
+          onIconBeforeClick={func}
+          iconBeforeAlt="icon-before"
+        />,
+      );
+      const iconBefore = screen.getByLabelText('icon-before');
+      await userEvent.click(iconBefore);
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+    it('onIconBeforeKeyDown is triggered', async () => {
+      const func = jest.fn();
+      render(
+        <TestChip
+          iconBefore={Close}
+          onIconBeforeClick={func}
+          iconBeforeAlt="icon-before"
+        />,
       );
-      const iconAfter = screen.getByTestId('icon-after');
-      await userEvent.type(iconAfter, '{enter}');
-      expect(func).toHaveBeenCalled();
+      const iconBefore = screen.getByLabelText('icon-before');
+      await userEvent.click(iconBefore, '{enter}', { skipClick: true });
+      expect(func).toHaveBeenCalledTimes(1);
+    });
+    it('checks the absence of the `selected` class in the chip', async () => {
+      render(<TestChip onClick={jest.fn} />);
+      const chip = screen.getByRole('button');
+      expect(chip).not.toHaveClass('selected');
+    });
+    it('checks the presence of the `selected` class in the chip', async () => {
+      render(<TestChip isSelected onClick={jest.fn} />);
+      const chip = screen.getByRole('button');
+      expect(chip).toHaveClass('selected');
     });
   });
 });

package/src/Chip/ChipIcon.tsx

@@ -0,0 +1,54 @@
+import React, { KeyboardEventHandler, MouseEventHandler } from 'react';
+import PropTypes from 'prop-types';
+import Icon from '../Icon';
+// @ts-ignore
+import IconButton from '../IconButton';
+// @ts-ignore
+import { STYLE_VARIANTS } from './constants';
+
+export interface ChipIconProps {
+  className: string,
+  src: React.ReactElement | Function,
+  onClick?: KeyboardEventHandler & MouseEventHandler,
+  alt?: string,
+  variant: string,
+  disabled?: boolean,
+}
+
+function ChipIcon({
+  className, src, onClick, alt, variant, disabled,
+}: ChipIconProps) {
+  if (onClick) {
+    return (
+      <IconButton
+        className={className}
+        src={src}
+        onClick={onClick}
+        iconAs={Icon}
+        alt={alt}
+        invertColors={variant === STYLE_VARIANTS.DARK}
+        tabIndex={disabled ? -1 : 0}
+      />
+    );
+  }
+
+  return <Icon src={src} className={className} size="sm" />;
+}
+
+ChipIcon.propTypes = {
+  className: PropTypes.string.isRequired,
+  src: PropTypes.oneOfType([PropTypes.element, PropTypes.func]).isRequired,
+  onClick: PropTypes.func,
+  alt: PropTypes.string,
+  variant: PropTypes.string,
+  disabled: PropTypes.bool,
+};
+
+ChipIcon.defaultProps = {
+  onClick: undefined,
+  alt: undefined,
+  variant: STYLE_VARIANTS.LIGHT,
+  disabled: false,
+};
+
+export default ChipIcon;

package/src/Chip/README.md

@@ -16,34 +16,139 @@ notes: |
 ## Basic Usage
 
 ```jsx live
-<div>
+<Stack
+  gap={2}
+  direction="horizontal"
+>
   <Chip>New</Chip>
   <Chip disabled>New</Chip>
-  <Chip variant="dark">New</Chip>
-</div>
+</Stack>
+```
+
+## Clickable Variant
+
+Use `onClick` prop to make the whole `Chip` clickable, this will also add appropriate styles to make `Chip` interactive.
+
+```jsx live
+<Chip onClick={() => console.log('Click!')}>Click Me</Chip>
+```
+
+## With isSelected prop
+
+```jsx live
+<Chip isSelected>New</Chip>
 ```
 
 ## With Icon Before and After
+### Basic Usage
+
+Use `iconBefore` and `iconAfter` props to provide icons for the `Chip`, note that you also can provide
+accessible names for these icons for screen reader support via `iconBeforeAlt` and `iconAfterAlt` respectively. 
 
 ```jsx live
-<div>
-  <Chip iconBefore={Person}>New</Chip>
+<Stack
+  gap={2}
+  direction="horizontal"
+>
+  <Chip iconBefore={Person} iconBeforeAlt="icon-before">Person</Chip>
+  <Chip iconAfter={Close} iconAfterAlt="icon-after">Close</Chip>
   <Chip
-    variant="dark"
     iconBefore={Person}
     iconAfter={Close}
-    onIconAfterClick={() => console.log('Remove Chip')}
+    iconAfterAlt="icon-after"
+    iconBeforeAlt="icon-before"
   >
-    New
+    Both
+  </Chip>
+</Stack>
+```
+
+### Clickable icon variant
+
+Provide click handlers for icons via `onIconAfterClick` and `onIconBeforeClick` props. 
+
+```jsx live
+<Stack
+  gap={2}
+  direction="horizontal"
+>
+  <Chip
+    iconBefore={Person}
+    iconBeforeAlt="icon-before"
+    onIconBeforeClick={() => console.log('onIconBeforeClick')}
+  >
+    Person
+  </Chip>
+  <Chip
+    iconAfter={Close}
+    onIconAfterClick={() => console.log('onIconAfterClick')}
+    iconAfterAlt="icon-after"
+  >
+    Close
   </Chip>
   <Chip
-    variant="dark"
     iconBefore={Person}
     iconAfter={Close}
-    onIconAfterClick={() => console.log('Remove Chip')}
+    onIconAfterClick={() => console.log('onIconAfterClick')}
+    onIconBeforeClick={() => console.log('onIconBeforeClick')}
+    iconAfterAlt="icon-after"
+    iconBeforeAlt="icon-before"
+  >
+    Both
+  </Chip>
+  <Chip
+    iconBefore={Person}
+    iconAfter={Close}
+    onIconAfterClick={() => console.log('onIconAfterClick')}
+    onIconBeforeClick={() => console.log('onIconBeforeClick')}
+    iconAfterAlt="icon-after"
+    iconBeforeAlt="icon-before"
+    disabled
+  >
+    Both
+  </Chip>
+</Stack>
+```
+
+**Note**: both `Chip` and its icons cannot be made interactive at the same time, e.g. if you provide both `onClick` and `onIconAfterClick` props,
+`onClick` will be ignored and only the icon will get interactive behaviour, see example below (this is done to avoid usability issues where users might click on the `Chip` itself by mistake when they meant to click the icon instead).
+
+```jsx live
+<Chip
+  iconBefore={Person}
+  iconBeforeAlt="icon-before"
+  onIconBeforeClick={() => console.log('onIconBeforeClick')}
+  onClick={() => console.log('onClick')}
+>
+  Person
+</Chip>
+```
+
+### Inverse Pallete
+
+```jsx live
+<Stack
+  className="bg-dark-700 p-4"
+  gap={2}
+  direction="horizontal"
+>
+  <Chip variant="dark" iconBefore={Person} iconBeforeAlt="icon-before">New</Chip>
+  <Chip
+    variant="dark"
+    iconAfter={Close}
+    onIconAfterClick={() => console.log('onIconAfterClick')}
+    iconAfterAlt="icon-after"
+  >
+    New 1
+  </Chip>
+  <Chip
+    variant="dark"
+    iconAfter={Close}
+    onIconAfterClick={() => console.log('onIconAfterClick')}
+    iconAfterAlt="icon-after"
     disabled
   >
     New
   </Chip>
-</div>
+</Stack>
 ```