@openedx/paragon 22.0.0-alpha.23 → 22.0.0

package/src/Form/form-autosuggest.mdx

@@ -19,93 +19,158 @@ Form auto-suggest enables users to manually select or type to find matching opti
 
 ```jsx live
 () => {
-    const [selected, setSelected] = useState('');
+  const [value, setValue] = useState({});
+  const [isValueRequired, setIsValueRequired] = useState(false);
+  const [isSelectionRequired, setIsSelectionRequired] = useState(false);
+  const [hasCustomValidation, setHasCustomValidation] = useState(false);
 
-    return (
-        <Form.Autosuggest
-            floatingLabel="Programming language"
-            aria-label="form autosuggest"
-            helpMessage="Select language"
-            errorMessageText="Error, no selected value"
-            value={selected}
-            onSelected={(value) => setSelected(value)}
-        >
-            <Form.AutosuggestOption>JavaScript</Form.AutosuggestOption>
-            <Form.AutosuggestOption>Python</Form.AutosuggestOption>
-            <Form.AutosuggestOption>Rube</Form.AutosuggestOption>
-            <Form.AutosuggestOption onClick={(e) => alert(e.currentTarget.getAttribute('data-value'))}>
-                Option with custom onClick
-            </Form.AutosuggestOption>
-        </Form.Autosuggest>
-    );
-}
-```
+  const hasCustomError = () => (hasCustomValidation ? value.selectionId !== 'c-option-id' : false);
 
-## Search Usage
+  const autosuggestRef = useRef();
+  const forceUpdateErrorState = () => {
+    autosuggestRef.current.updateErrorStateAndErrorMessage();
+  };
 
-```jsx live
-() => {
-    const [selected, setSelected] = useState('');
-
-    return (
+  return (
+    <>
+      <Form.Group>
+        <Form.Label>
+          <h4>Programming language</h4>
+        </Form.Label>
         <Form.Autosuggest
-            placeholder="Type 'T'"
-            aria-label="form autosuggest"
-            errorMessageText="Error, no selected value"
-            helpMessage="Select language"
-            value={selected}
-            onSelected={(value) => setSelected(value)}
+          ref={autosuggestRef}
+          aria-label="form autosuggest"
+          helpMessage="Select language"
+          value={value}
+          onChange={(v) => setValue(v)}
+          isValueRequired={isValueRequired}
+          valueRequiredErrorMessageText="Error: value required"
+          isSelectionRequired={isSelectionRequired}
+          selectionRequiredErrorMessageText="Error: selection required"
+          hasCustomError={hasCustomError()}
+          customErrorMessageText="Error: selected language less than 50 years old"
         >
-            <Form.AutosuggestOption>PHP</Form.AutosuggestOption>
-            <Form.AutosuggestOption>Java</Form.AutosuggestOption>
-            <Form.AutosuggestOption>Turbo Pascal</Form.AutosuggestOption>
-            <Form.AutosuggestOption>Flask</Form.AutosuggestOption>
+          <Form.AutosuggestOption id="javascript-option-id">JavaScript</Form.AutosuggestOption>
+          <Form.AutosuggestOption id="python-option-id">Python</Form.AutosuggestOption>
+          <Form.AutosuggestOption id="ruby-option-id">Ruby</Form.AutosuggestOption>
+          <Form.AutosuggestOption id="c-option-id">C</Form.AutosuggestOption>
         </Form.Autosuggest>
-    );
-}
+      </Form.Group>
+      <Form.Group>
+        <Form.CheckboxSet isInline>
+          <Form.Checkbox checked={isValueRequired} onChange={e => setIsValueRequired(e.target.checked)}>Value Required</Form.Checkbox>
+          <Form.Checkbox checked={isSelectionRequired} onChange={e => setIsSelectionRequired(e.target.checked)}>Selection Required</Form.Checkbox>
+          <Form.Checkbox checked={hasCustomValidation} onChange={e => setHasCustomValidation(e.target.checked)}>Custom Validation</Form.Checkbox>
+        </Form.CheckboxSet>
+      </Form.Group>
+      <Collapsible styling="basic" title="Value details">
+        <Row>
+          <Col xs={3}><pre>userProvidedText:</pre></Col>
+          <Col><pre>{value.userProvidedText}</pre></Col>
+        </Row>
+        <Row>
+          <Col xs={3}><pre>selectionValue:</pre></Col>
+          <Col><pre>{value.selectionValue}</pre></Col>
+        </Row>
+        <Row>
+          <Col xs={3}><pre>selectionId:</pre></Col>
+          <Col><pre>{value.selectionId}</pre></Col>
+        </Row>
+      </Collapsible>
+      <Collapsible styling="basic" title="External modification">
+        <Form.Group className="mb-3">
+          <Form.Label>User provided text</Form.Label>
+          <Form.Control
+            onChange={(e) => setValue({
+              userProvidedText: e.target.value,
+              selectionValue: '',
+              selectionId: '',
+            })}
+            value={value.userProvidedText}
+          />
+        </Form.Group>
+        <Button onClick={forceUpdateErrorState}>Trigger validation</Button>
+      </Collapsible>
+    </>
+  );
+};
 ```
 
 ## Loading state
 
 ```jsx live
 () => {
-    const [data, setData] = useState([]);
-    const [showLoading, setShowLoading] = useState(false);
+  const [userProvidedText, setUserProvidedText] = useState('');
+  const [selectionValue, setSelectionValue] = useState('');
+  const [selectionId, setSelectionId] = useState('');
+  const [data, setData] = useState([]);
+  const [showLoading, setShowLoading] = useState(false);
+
+  useEffect(() => {
+    setShowLoading(true);
+    fetch('https://api.sampleapis.com/coffee/hot')
+      .then(data => data.json())
+      .then(items => {
+        setTimeout(() => {
+          setData(items);
+          setShowLoading(false);
+        }, 1500);
+      });
+  }, []);
 
-    useEffect(() => {
-        setShowLoading(true);
-        fetch('https://api.sampleapis.com/coffee/hot')
-            .then(data => data.json())
-            .then(items => {
-                setTimeout(() => {
-                  setData(items);
-                  setShowLoading(false);
-                }, 1500);
-            });
-    }, [])
+  const searchCoffee = (title, id) => {
+    if (!id) {
+      setShowLoading(true);
+    }
+    fetch('https://api.sampleapis.com/coffee/hot')
+      .then(data => data.json())
+      .then(items => setTimeout(() => {
+        const filteredCoffee = items.filter(res => res.title.toLowerCase().includes(title.toLowerCase()));
+        setShowLoading(false);
+        if (filteredCoffee) { return filteredCoffee; }
+        return { ...title, filteredCoffee };
+      }, 1500));
+  };
 
-    const searchCoffee = (title) => {
-        setShowLoading(true);
-        fetch('https://api.sampleapis.com/coffee/hot')
-            .then(data => data.json())
-            .then(items => setTimeout(() => {
-                const filteredCoffee = items.filter(res => res.title.toLowerCase().includes(title.toLowerCase()));
-                setShowLoading(false);
-                if (filteredCoffee) { return filteredCoffee }
-                return { ...title, filteredCoffee }
-        }, 1500));
-    };
+  const valueChanged = (value) => {
+    if (userProvidedText !== value.userProvidedText) {
+      searchCoffee(value.userProvidedText, value.selectionId);
+    }
+    setUserProvidedText(value.userProvidedText);
+    setSelectionValue(value.selectionValue);
+    setSelectionId(value.selectionId);
+  };
 
-    return (
+  return (
+    <>
+      <Form.Group>
+        <Form.Label>
+          <h4>Café API</h4>
+        </Form.Label>
         <Form.Autosuggest
-            isLoading={showLoading}
-            placeholder="This is placeholder"
-            floatingLabel="This is floating label"
-            screenReaderText="Loading..."
-            onChange={searchCoffee}
+          isLoading={showLoading}
+          placeholder="This is placeholder"
+          screenReaderText="Loading..."
+          onChange={valueChanged}
         >
-            {data.map((item, index) => <Form.AutosuggestOption key={index}>{item.title}</Form.AutosuggestOption>)}
+          {data.map((item, index) => <Form.AutosuggestOption key={index}>{item.title}</Form.AutosuggestOption>)}
         </Form.Autosuggest>
-    );
-}
+      </Form.Group>
+      <Collapsible styling="basic" title="Value details">
+        <Row>
+          <Col xs={3}><pre>userProvidedText:</pre></Col>
+          <Col><pre>{userProvidedText}</pre></Col>
+        </Row>
+        <Row>
+          <Col xs={3}><pre>selectionValue:</pre></Col>
+          <Col><pre>{selectionValue}</pre></Col>
+        </Row>
+        <Row>
+          <Col xs={3}><pre>selectionId:</pre></Col>
+          <Col><pre>{selectionId}</pre></Col>
+        </Row>
+      </Collapsible>
+    </>
+  );
+};
 ```

package/src/Form/tests/FormAutosuggest.test.jsx

@@ -6,6 +6,8 @@ import userEvent from '@testing-library/user-event';
 import { IntlProvider } from 'react-intl';
 import FormAutosuggest from '../FormAutosuggest';
 import FormAutosuggestOption from '../FormAutosuggestOption';
+import FormGroup from '../FormGroup';
+import FormLabel from '../FormLabel';
 
 function FormAutosuggestWrapper(props) {
   return (
@@ -21,26 +23,48 @@ function FormAutosuggestTestComponent(props) {
       name="FormAutosuggest"
       floatingLabel="floatingLabel text"
       helpMessage="Example help message"
-      errorMessageText="Example error message"
-      onSelected={props.onSelected}
+      valueRequiredErrorMessageText="Example value required error message"
+      selectionRequiredErrorMessageText="Example selection required error message"
+      customErrorMessageText="Example custom error message"
+      onChange={props.onChange}
+      isValueRequired={props.isValueRequired}
+      isSelectionRequired={props.isSelectionRequired}
+      hasCustomError={props.hasCustomError}
     >
-      <FormAutosuggestOption>Option 1</FormAutosuggestOption>
+      <FormAutosuggestOption id="option-1-id">Option 1</FormAutosuggestOption>
       <FormAutosuggestOption onClick={props.onClick}>Option 2</FormAutosuggestOption>
       <FormAutosuggestOption>Learn from more than 160 member universities</FormAutosuggestOption>
     </FormAutosuggestWrapper>
   );
 }
 
+function FormAutosuggestLabelTestComponent() {
+  return (
+    <FormGroup>
+      <FormLabel data-testid="autosuggest-label">
+        <h3>Label</h3>
+      </FormLabel>
+      <FormAutosuggestWrapper>
+        <FormAutosuggestOption>Option</FormAutosuggestOption>
+      </FormAutosuggestWrapper>
+    </FormGroup>
+  );
+}
+
 FormAutosuggestTestComponent.defaultProps = {
-  onSelected: jest.fn(),
+  onChange: jest.fn(),
   onClick: jest.fn(),
+  isValueRequired: false,
+  isSelectionRequired: false,
+  hasCustomError: false,
 };
 
 FormAutosuggestTestComponent.propTypes = {
-  /** Specifies onSelected event handler. */
-  onSelected: PropTypes.func,
-  /** Specifies onClick event handler. */
+  onChange: PropTypes.func,
   onClick: PropTypes.func,
+  isValueRequired: PropTypes.bool,
+  isSelectionRequired: PropTypes.bool,
+  hasCustomError: PropTypes.bool,
 };
 
 describe('render behavior', () => {
@@ -61,7 +85,7 @@ describe('render behavior', () => {
   });
 
   it('renders the auto-populated value if it exists', () => {
-    render(<FormAutosuggestWrapper value="Test Value" />);
+    render(<FormAutosuggestWrapper value={{ userProvidedText: 'Test Value' }} />);
     expect(screen.getByDisplayValue('Test Value')).toBeInTheDocument();
   });
 
@@ -73,15 +97,42 @@ describe('render behavior', () => {
     expect(list.length).toBe(3);
   });
 
-  it('renders with error msg', () => {
-    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent />);
+  it('renders with value required error msg', () => {
+    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent isValueRequired />);
+    const input = getByTestId('autosuggest-textbox-input');
+
+    // if you click into the input and click outside, you should see the error message
+    userEvent.click(input);
+    userEvent.click(document.body);
+
+    const formControlFeedback = getByText('Example value required error message');
+
+    expect(formControlFeedback).toBeInTheDocument();
+  });
+
+  it('renders with selection required error msg', () => {
+    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent isSelectionRequired />);
     const input = getByTestId('autosuggest-textbox-input');
 
     // if you click into the input and click outside, you should see the error message
     userEvent.click(input);
+    userEvent.type(input, '1');
     userEvent.click(document.body);
 
-    const formControlFeedback = getByText('Example error message');
+    const formControlFeedback = getByText('Example selection required error message');
+
+    expect(formControlFeedback).toBeInTheDocument();
+  });
+
+  it('renders with custom error msg', () => {
+    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent hasCustomError />);
+    const input = getByTestId('autosuggest-textbox-input');
+
+    // if you click into the input and click outside, you should see the error message
+    userEvent.click(input);
+    userEvent.click(document.body);
+
+    const formControlFeedback = getByText('Example custom error message');
 
     expect(formControlFeedback).toBeInTheDocument();
   });
@@ -112,6 +163,12 @@ describe('render behavior', () => {
 
     expect(getByText('3 options found')).toBeInTheDocument();
   });
+
+  it('associates labels with the input textbox', () => {
+    const { getByTestId } = render(<FormAutosuggestLabelTestComponent />);
+
+    expect(getByTestId('autosuggest-label').getAttribute('for')).toEqual(getByTestId('autosuggest-textbox-input').getAttribute('id'));
+  });
 });
 
 describe('controlled behavior', () => {
@@ -126,17 +183,28 @@ describe('controlled behavior', () => {
     expect(input.value).toEqual('Option 1');
   });
 
-  it('calls onSelected based on clicked option', () => {
-    const onSelected = jest.fn();
-    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent onSelected={onSelected} />);
+  it('calls onChange based on clicked option', () => {
+    const onChange = jest.fn();
+    const { getByText, getByTestId } = render(<FormAutosuggestTestComponent onChange={onChange} />);
     const input = getByTestId('autosuggest-textbox-input');
 
     userEvent.click(input);
     const menuItem = getByText('Option 1');
     userEvent.click(menuItem);
 
-    expect(onSelected).toHaveBeenCalledWith('Option 1');
-    expect(onSelected).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith({ selectionId: 'option-1-id', selectionValue: 'Option 1', userProvidedText: 'Option 1' });
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onChange when the textbox is cleared', () => {
+    const onChange = jest.fn();
+    const { getByTestId } = render(<FormAutosuggestTestComponent onChange={onChange} />);
+    const input = getByTestId('autosuggest-textbox-input');
+
+    userEvent.type(input, '1');
+    userEvent.type(input, '{backspace}');
+
+    expect(onChange).toHaveBeenCalledWith({ selectionId: '', selectionValue: '', userProvidedText: '' });
   });
 
   it('calls the function passed to onClick when an option with it is selected', () => {

package/src/Hyperlink/index.jsx

@@ -101,18 +101,19 @@ Hyperlink.propTypes = {
   children: PropTypes.node.isRequired,
   /** Custom class names for the hyperlink */
   className: PropTypes.string,
-  /** specifies where the link should open. The default behavior is `_self`, which means that the URL will be 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).
-   */
+  /** specifies where the link should open. The default behavior is `_self`, which means that the URL will be
+   * 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,
   /** specifies the callback function when the link is clicked */
   onClick: PropTypes.func,
-  // eslint-disable-next-line max-len
   /** 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',
   ),
-  // eslint-disable-next-line max-len
   /** specifies the title for links with a `_blank` target (which loads the URL in a new browsing context). */
   externalLinkTitle: isRequiredIf(
     PropTypes.string,
@@ -120,9 +121,9 @@ Hyperlink.propTypes = {
   ),
   /** type of hyperlink */
   variant: PropTypes.oneOf(['default', 'muted', 'brand']),
-  /** specify the link style. By default it will be underlined. */
+  /** specify the link style. By default, it will be underlined. */
   isInline: PropTypes.bool,
-  /** specify if we need to show launch Icon. By default it will be visible. */
+  /** specify if we need to show launch Icon. By default, it will be visible. */
   showLaunchIcon: PropTypes.bool,
 };
 

package/src/Hyperlink/index.scss

@@ -1,9 +1,9 @@
 .pgn__hyperlink {
+  display: inline-flex;
+  align-items: center;
   text-align: start;
 
   &__external-icon {
-    display: inline-block;
-    vertical-align: middle;
-    margin-inline-start: var(--pgn-spacing-spacer-2);
+    margin-inline-start: map_get($spacers, 2);
   }
 }

package/src/Icon/README.md

@@ -11,13 +11,13 @@ devStatus: 'Done'
 notes: |
 ---
 
-Displays an svg icon from `@edx/paragon/icons`. See [Icons Foundation Documentation](/foundations/icons) for a list of all available icons.
+Displays an svg icon from `@openedx/paragon/icons`. See [Icons Foundation Documentation](/foundations/icons) for a list of all available icons.
 
 ## Basic Usage
 
 ```jsx live
 // Included in this live jsx scope:
-// import { Add, AddCircle } from '@edx/paragon/icons';
+// import { Add, AddCircle } from '@openedx/paragon/icons';
 <Icon src={Add} />
 ```
 ### With HTML attributes
@@ -26,7 +26,7 @@ HTML attributes can be passed to this component allowing for customization of th
 
 ```jsx live
 // Included in this live jsx scope:
-// import { Add, AddCircle } from '@edx/paragon/icons';
+// import { Add, AddCircle } from '@openedx/paragon/icons';
 <div className="d-flex align-items-center bg-dark">
   <Icon src={Add} className="mx-3 text-white" />
   <Icon src={Add} className="mx-3 text-white" size="xs" />

package/src/Icon/_variables.scss

@@ -0,0 +1,7 @@
+// Icons sizes
+
+$icon-inline: .8em !default;
+$icon-xs: 1rem !default;
+$icon-sm: 1.25rem !default;
+$icon-md: 1.5rem !default;
+$icon-lg: 1.75rem !default;

package/src/Icon/index.jsx

@@ -70,28 +70,35 @@ function Icon({
 }
 
 Icon.propTypes = {
-  // eslint-disable-next-line max-len
-  /** An icon component to render. Example import of a Paragon icon component: `import { Check } from '@edx/paragon/dist/icon';` */
-  src: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  /**
+   * 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]),
   /** HTML element attributes to pass through to the underlying svg element */
   svgAttrs: PropTypes.shape({
     'aria-label': PropTypes.string,
     'aria-labelledby': PropTypes.string,
   }),
-  // eslint-disable-next-line max-len
-  /** the `id` property of the Icon element, by default this value is generated with the `newId` function with the `prefix` of `Icon`. */
+  /**
+   * the `id` property of the Icon element, by default this value is generated
+   * with the `newId` function with the `prefix` of `Icon`.
+   */
   id: PropTypes.string,
-  // eslint-disable-next-line max-len
   /** The size of the icon. */
   size: PropTypes.oneOf(['xs', 'sm', 'md', 'lg']),
-  // eslint-disable-next-line max-len
   /** A class name that will define what the Icon looks like. */
   className: PropTypes.string,
-  // eslint-disable-next-line max-len
-  /** a boolean that determines the value of `aria-hidden` attribute on the Icon span, this value is `true` by default. */
+  /**
+   * a boolean that determines the value of `aria-hidden` attribute on the Icon span,
+   * this value is `true` by default.
+   */
   hidden: PropTypes.bool,
-  // eslint-disable-next-line max-len
-  /** a string or an element that will be used on a secondary span leveraging the `sr-only` style for screenreader only text, this value is `undefined` by default. This value is recommended for use unless the Icon is being used in a way that is purely decorative or provides no additional context for screen reader users. This field should be thought of the same way an `alt` attribute would be used for `image` tags.
+  /**
+   * a string or an element that will be used on a secondary span leveraging the `sr-only` style
+   * for screenreader only text, this value is `undefined` by default. This value is recommended for use unless
+   * the Icon is being used in a way that is purely decorative or provides no additional context for screen
+   * reader users. This field should be thought of the same way an `alt` attribute would be used for `image` tags.
    */
   screenReaderText: PropTypes.oneOfType([PropTypes.string, PropTypes.element]),
 };

package/src/Icon/index.scss

@@ -1,3 +1,5 @@
+@import "variables";
+
 .pgn__icon {
   display: block;
   height: 1.5rem; // 24px, Assumes base font size to be 16px
@@ -6,28 +8,28 @@
   flex-shrink: 0;
 
   &.pgn__icon__inline {
-    width: var(--pgn-size-icon-inline);
-    height: var(--pgn-size-icon-inline);
+    width: $icon-inline;
+    height: $icon-inline;
   }
 
   &.pgn__icon__xs {
-    width: var(--pgn-size-icon-xs);
-    height: var(--pgn-size-icon-xs);
+    width: $icon-xs;
+    height: $icon-xs;
   }
 
   &.pgn__icon__sm {
-    width: var(--pgn-size-icon-sm);
-    height: var(--pgn-size-icon-sm);
+    width: $icon-sm;
+    height: $icon-sm;
   }
 
   &.pgn__icon__md {
-    width: var(--pgn-size-icon-md);
-    height: var(--pgn-size-icon-md);
+    width: $icon-md;
+    height: $icon-md;
   }
 
   &.pgn__icon__lg {
-    width: var(--pgn-size-icon-lg);
-    height: var(--pgn-size-icon-lg);
+    width: $icon-lg;
+    height: $icon-lg;
   }
 }