@openedx/paragon 22.0.0-alpha.24 → 22.0.0

package/src/InputText/README.md

@@ -0,0 +1,293 @@
+---
+title: 'InputText'
+type: 'component'
+components:
+- InputText
+categories:
+- Forms (deprecated)
+status: 'Deprecate Soon'
+designStatus: 'TBD'
+devStatus: 'To Do'
+notes: |
+  Replaced by Form.Control
+---
+
+## Minimal usage
+
+```jsx live
+<InputText name="name" label="First Name" value="Foo Bar" />
+```
+
+## Read only
+
+```jsx live
+<InputText name="inputState" label="Input State" value="Read Only" readOnly />
+```
+
+## Validation
+
+```jsx live
+<InputText
+  id="username"
+  name="username"
+  label="Username"
+  description="The unique name that identifies you throughout the site."
+  validator={value => {
+    let feedback = { isValid: true };
+    if (value.length < 3) {
+      feedback = {
+        isValid: false,
+        validationMessage: 'Username must be at least 3 characters in length.',
+      };
+    }
+    return feedback;
+  }}
+/>
+```
+
+### Validation with danger theme
+
+```jsx live
+<InputText
+  name="username"
+  label="Username"
+  description="The unique name that identifies you throughout the site."
+  validator={value => {
+    let feedback = { isValid: true };
+    if (value.length < 3) {
+      feedback = {
+        isValid: false,
+        validationMessage: 'Username must be at least 3 characters in length.',
+        dangerIconDescription: 'Error',
+      };
+    }
+    return feedback;
+  }}
+  themes={['danger']}
+/>
+```
+
+### Label as element
+
+```jsx live
+<InputText
+  name="username"
+  label={<span lang="en">Element</span>}
+  value="Label is wrapped in language span"
+/>
+```
+
+### Focus test
+
+```jsx live
+class FocusInputWrapper extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { open: true };
+
+    this.resetStatusAlertWrapperState = this.resetStatusAlertWrapperState.bind(
+      this,
+    );
+  }
+
+  resetStatusAlertWrapperState() {
+    this.setState({ open: false });
+    this.inputForm.focus();
+  }
+
+  render() {
+    return (
+      <div>
+        <StatusAlert
+          alertType="info"
+          open={this.state.open}
+          dialog="Close me to input data!"
+          onClose={this.resetStatusAlertWrapperState}
+        />
+        <InputText
+          id="data"
+          name="data"
+          label="Data Input"
+          inputRef={input => {
+            this.inputForm = input;
+          }}
+        />
+      </div>
+    );
+  }
+}
+```
+
+### Different textual input types
+
+```jsx live
+<form>
+  <InputText
+    name="search"
+    label="Search"
+    value="what is paragon"
+    type="search"
+    id="input-search"
+  />
+  <InputText
+    name="email"
+    label="Email"
+    value="paragon@edx.org"
+    type="email"
+    id="input-email"
+  />
+  <InputText
+    name="url"
+    label="Url"
+    value="https://edx.github.io/paragon"
+    type="url"
+    id="input-url"
+  />
+  <InputText
+    name="telephone"
+    label="Telephone"
+    value="1-(555)-555-5555"
+    type="tel"
+    id="input-tel"
+  />
+  <InputText
+    name="password"
+    label="Password"
+    value="hunter2"
+    type="password"
+    id="input-password"
+  />
+  <InputText
+    name="number"
+    label="Number"
+    value={42}
+    type="number"
+    id="input-number"
+  />
+  <InputText
+    name="datetime-local"
+    label="Date and time"
+    value="2017-04-27T13:45:00"
+    type="datetime-local"
+    id="input-datetime-local"
+  />
+  <InputText
+    name="date"
+    label="Date"
+    value="2017-04-27"
+    type="date"
+    id="input-date"
+  />
+  <InputText
+    name="month"
+    label="Month"
+    value="2017-04"
+    type="month"
+    id="input-month"
+  />
+  <InputText
+    name="week"
+    label="Week"
+    value="2017-W33"
+    type="week"
+    id="input-week"
+  />
+  <InputText
+    name="time"
+    label="Time"
+    value="13:45:00"
+    type="time"
+    id="input-time"
+  />
+  <InputText
+    name="color"
+    label="Color"
+    value="#BF472C"
+    type="color"
+    id="input-color"
+  />
+</form>
+```
+
+### Price with step
+
+```jsx live
+<InputText
+  name="price"
+  label="Price"
+  type="number"
+  value={3.5}
+  min={0}
+  step={0.01}
+/>
+```
+
+### Displayed inline
+
+```jsx live
+<InputText name="username" label="Username" value="foobar" inline />
+```
+
+### With input group addons
+
+```jsx live
+<form>
+  <InputText
+    name="username"
+    label="Username"
+    value="foobar"
+    inputGroupPrepend={<div className="input-group-text">{'@'}</div>}
+  />
+  <InputText
+    name="username"
+    label="Username"
+    value="foobar"
+    inputGroupAppend={<div className="input-group-text">{'@example.com'}</div>}
+  />
+  <InputText
+    name="money"
+    label="Money"
+    type="number"
+    value={1000}
+    inputGroupPrepend={<div className="input-group-text">{'$'}</div>}
+    inputGroupAppend={<div className="input-group-text">{'.00'}</div>}
+  />
+  <InputText
+    name="search"
+    label="Search"
+    value="what is paragon"
+    inputGroupAppend={(
+      <Button variant="outline-secondary">Go</Button>
+    )}
+  />
+  <InputText
+    name="username"
+    label="Username"
+    value="foobar"
+    inputGroupAppend={[
+      <div className="input-group-text">
+        <Icon
+          id="checkmark"
+          className="fa fa-check"
+          screenReaderText="Checkmark"
+        />
+      </div>,
+      <Button variant="outline-secondary">Go</Button>,
+    ]}
+  />
+  <InputText
+    name="password"
+    label="Password"
+    value="secret"
+    inputGroupAppend={
+      <div className="input-group-text">
+        <Icon
+          id="checkmark"
+          className="fa fa-check"
+          screenReaderText="Checkmark"
+        />
+      </div>
+    }
+  />
+</form>
+```

package/src/InputText/index.jsx

@@ -0,0 +1,49 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+import asInput from '../asInput';
+import withDeprecatedProps, { DeprTypes } from '../withDeprecatedProps';
+
+function Text(props) {
+  const {
+    className,
+    inputRef,
+    type,
+    ...others
+  } = props;
+
+  return (
+    <input
+      {...others}
+      className={className}
+      type={type || 'text'}
+      ref={inputRef}
+    />
+  );
+}
+
+Text.propTypes = {
+  className: PropTypes.string,
+  inputRef: PropTypes.oneOfType([
+    PropTypes.func,
+    PropTypes.shape({ current: PropTypes.instanceOf(PropTypes.element) }),
+  ]),
+  type: PropTypes.string,
+};
+
+Text.defaultProps = {
+  className: undefined,
+  inputRef: undefined,
+  type: 'text',
+};
+
+const InputText = asInput(withDeprecatedProps(Text, 'InputText', {
+  className: {
+    deprType: DeprTypes.FORMAT,
+    expect: value => typeof value === 'string',
+    transform: value => (Array.isArray(value) ? value.join(' ') : value),
+    message: 'It should be a string.',
+  },
+}));
+
+export default InputText;

package/src/ListBox/ListBox.test.jsx

@@ -0,0 +1,161 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import ListBox from '.';
+import ListBoxOption from '../ListBoxOption';
+
+describe('ListBox', () => {
+  beforeEach(() => {
+    render(
+      <ListBox>
+        <ListBoxOption>test1</ListBoxOption>
+        <ListBoxOption>test2</ListBoxOption>
+        <ListBoxOption>test3</ListBoxOption>
+      </ListBox>,
+    );
+  });
+
+  it('should have null aria-activedescendant attribute by default', () => {
+    const listBoxElement = screen.getByRole('listbox');
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toBeNull();
+  });
+
+  it(
+    'should have correct aria-activedescendant attribute when selectedOptionIndex state is non-null',
+    async () => {
+      const listBoxElement = screen.getByRole('listbox');
+      const selectedOptionIndex = 1;
+
+      listBoxElement.focus();
+
+      await userEvent.keyboard('{arrowdown}');
+
+      expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual(`list-box-option-${selectedOptionIndex}`);
+    },
+  );
+
+  it('selectedOptionIndex prop should override selectedOptionIndex state', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+    const selectedOptionIndex = 2;
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowdown}');
+    await userEvent.keyboard('{arrowdown}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual(`list-box-option-${selectedOptionIndex}`);
+  });
+
+  it('should render a div by default', () => {
+    const listBoxElement = screen.getByRole('listbox');
+    expect(listBoxElement.tagName.toLowerCase()).toBe('div');
+  });
+
+  it('should render an HTML element when passed tag prop is an HTML element', () => {
+    const { container } = render(
+      <ListBox tag="li">
+        <ListBoxOption>test1</ListBoxOption>
+      </ListBox>,
+    );
+    const listBoxElement = container.querySelector('li');
+    expect(listBoxElement).toBeInTheDocument();
+  });
+
+  it('should have correct default classNames', () => {
+    const listBoxElement = screen.getByRole('listbox');
+    expect(listBoxElement).toHaveClass('list-group');
+  });
+
+  it('should have listbox role', () => {
+    const listBoxElement = screen.getByRole('listbox');
+    expect(listBoxElement).toHaveAttribute('role', 'listbox');
+  });
+
+  it('should have 0 tabIndex', () => {
+    const listBoxElement = screen.getByRole('listbox');
+    expect(listBoxElement).toHaveAttribute('tabIndex', '0');
+  });
+
+  it('should select first ListBoxOption on focus if not ListBoxOption selected', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-0');
+  });
+
+  it('should not select first ListBoxOption on focus if ListBoxOption selected', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowdown}');
+
+    listBoxElement.focus();
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-1');
+  });
+
+  it('should select next ListBoxOption on down arrow key', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowdown}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-1');
+  });
+
+  it('should not select next ListBoxOption on down arrow key if at end of list', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowdown}');
+    await userEvent.keyboard('{arrowdown}');
+    await userEvent.keyboard('{arrowdown}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-2');
+  });
+
+  it('should select previous ListBoxOption on up arrow key', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowdown}');
+    await userEvent.keyboard('{arrowup}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-0');
+  });
+
+  it('should not select previous ListBoxOption on up arrow key if at start of list', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{arrowup}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-0');
+  });
+
+  it('should not change ListBoxOption selection on non-supported key', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+
+    listBoxElement.focus();
+
+    await userEvent.keyboard('{leftarrow}');
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-0');
+  });
+
+  it('should update state when child\'s onSelect is called', async () => {
+    const listBoxElement = screen.getByRole('listbox');
+    const listBoxOption2 = screen.getAllByRole('option')[1];
+
+    await userEvent.click(listBoxOption2);
+
+    expect(listBoxElement.getAttribute('aria-activedescendant')).toEqual('list-box-option-1');
+  });
+});

package/src/ListBox/README.md

@@ -0,0 +1,185 @@
+---
+title: 'ListBox'
+type: 'component'
+components:
+- ListBox
+- ListBoxOption
+categories:
+- Forms (deprecated)
+status: 'Deprecate Soon'
+designStatus: 'TBD'
+devStatus: 'To Do'
+notes: 'Not used anywhere in code on Github. Consult design.'
+---
+
+## basic usage
+
+```jsx live
+<ListBox>
+  <ListBoxOption>
+    Apple
+  </ListBoxOption>
+  <ListBoxOption>
+    Orange
+  </ListBoxOption>
+  <ListBoxOption>
+    Strawberry
+  </ListBoxOption>
+  <ListBoxOption>
+    Banana
+  </ListBoxOption>
+</ListBox>
+```
+
+## using tag prop
+
+```jsx live
+<React.Fragment>
+  <div>This is an ordered list!</div>
+  <ListBox tag="ol">
+    <ListBoxOption tag="li">
+      Apple
+    </ListBoxOption>
+    <ListBoxOption tag="li">
+      <div>Orange</div>
+    </ListBoxOption>
+    <ListBoxOption tag="li">
+      Strawberry
+    </ListBoxOption>
+    <ListBoxOption tag="li">
+      Banana
+    </ListBoxOption>
+  </ListBox>
+</React.Fragment>
+```
+
+## using onSelect prop
+
+```jsx live
+class ListBoxWrapperForOnSelect extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.onSelect = this.onSelect.bind(this);
+
+    this.state = {
+      selectedOption: null,
+      selectedOptionIndex: null,
+    };
+
+    this.fruits = {
+      Apple: '🍎',
+      Orange: '🍊',
+      Strawberry: '🍓',
+      Banana: '🍌',
+    };
+  }
+
+  onSelect(option, index) {
+    this.setState({
+      selectedOption: option,
+      selectedOptionIndex: index,
+    });
+  }
+
+  getSelectedFruitEmoji(fruit) {
+    return fruit ? this.fruits[fruit] : '';
+  }
+
+  render() {
+    const children = Object.keys(this.fruits).map((fruit, index) => (
+      <ListBoxOption
+        key={fruit}
+        onSelect={() => this.onSelect(fruit, index)}
+        style={{ textAlign: 'center' }}
+      >
+        {fruit}
+      </ListBoxOption>
+    ));
+
+    return (
+      <React.Fragment>
+        <span aria-live="polite">
+          Selected Fruit:
+          {this.state.selectedOptionIndex === undefined ? (
+            <span className="sr-only">none</span>
+          ) : (
+            <span
+              arialabelledby={`list-box-option-${
+                this.state.selectedOptionIndex
+              }`}
+            >
+              {this.getSelectedFruitEmoji(this.state.selectedOption)}
+            </span>
+          )}
+        </span>
+        <ListBox style={{ width: '200px' }}>
+          {children}
+        </ListBox>
+      </React.Fragment>
+    );
+  }
+}
+```
+
+## using selectedOptionIndex prop
+
+```jsx live
+class ListBoxWrapperForSelectedOptionIndex extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.onSelect = this.onSelect.bind(this);
+    this.onButtonClick = this.onButtonClick.bind(this);
+
+    this.state = {
+      reset: true,
+    };
+
+    this.fruits = Object.keys({
+      Apple: '🍎',
+      Orange: '🍊',
+      Strawberry: '🍓',
+      Banana: '🍌',
+    });
+  }
+
+  onButtonClick() {
+    this.setState({
+      reset: true,
+    });
+  }
+
+  onSelect() {
+    this.setState({
+      reset: false,
+    });
+  }
+
+  render() {
+    const children = this.fruits.map(fruit => (
+      <ListBoxOption
+        key={fruit}
+        onSelect={this.onSelect}
+        style={{ textAlign: 'center' }}
+      >
+        {fruit}
+      </ListBoxOption>
+    ));
+
+    return (
+      <React.Fragment>
+        <Button variant="primary" onClick={this.onButtonClick}>
+          Click me to reset your selected fruit!
+        </Button>
+        <ListBox
+          selectedOptionIndex={this.state.reset ? null : undefined}
+          style={{ margin: '10px' }}
+        >
+          {children}
+        </ListBox>
+      </React.Fragment>
+    );
+  }
+}
+```