feat(react): enable textarea to limit text input to set amount of words

.all-contributorsrc

@@ -1167,6 +1167,30 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "matejoslav",
+      "name": "Matej Ocovsky",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8973672?v=4",
+      "profile": "https://github.com/matejoslav",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "SamChinellato",
+      "name": "SamChinellato",
+      "avatar_url": "https://avatars.githubusercontent.com/u/49278203?v=4",
+      "profile": "https://samuelechinellato.com/#/",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "stevenpatrick009",
+      "name": "stevenpatrick009",
+      "avatar_url": "https://avatars.githubusercontent.com/u/106097350?v=4",
+      "profile": "https://github.com/stevenpatrick009"
     }
   ],
   "commitConvention": "none"

README.md

@@ -240,6 +240,11 @@ check out our [Contributing Guide](/.github/CONTRIBUTING.md) and our
     <td align="center"><a href="http://www.steveblackonline.com/"><img src="https://avatars.githubusercontent.com/u/7853451?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Steven Black</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=sjbeatle" title="Code">💻</a> <a href="#a11y-sjbeatle" title="Accessibility">️️️️♿️</a></td>
     <td align="center"><a href="https://github.com/mrkjdy"><img src="https://avatars.githubusercontent.com/u/32761859?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Mark Judy</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=mrkjdy" title="Code">💻</a></td>
   </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/matejoslav"><img src="https://avatars.githubusercontent.com/u/8973672?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Matej Ocovsky</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=matejoslav" title="Code">💻</a></td>
+    <td align="center"><a href="https://samuelechinellato.com/#/"><img src="https://avatars.githubusercontent.com/u/49278203?v=4?s=100" width="100px;" alt=""/><br /><sub><b>SamChinellato</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=SamChinellato" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/stevenpatrick009"><img src="https://avatars.githubusercontent.com/u/106097350?v=4?s=100" width="100px;" alt=""/><br /><sub><b>stevenpatrick009</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=stevenpatrick009" title="Code">💻</a></td>
+  </tr>
 </table>
 
 <!-- markdownlint-restore -->

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -7986,6 +7986,7 @@ Map {
   "TextArea" => Object {
     "$$typeof": Symbol(react.forward_ref),
     "defaultProps": Object {
+      "counterMode": "character",
       "disabled": false,
       "enableCounter": false,
       "helperText": "",
@@ -8006,6 +8007,15 @@ Map {
       "cols": Object {
         "type": "number",
       },
+      "counterMode": Object {
+        "args": Array [
+          Array [
+            "character",
+            "word",
+          ],
+        ],
+        "type": "oneOf",
+      },
       "defaultValue": Object {
         "args": Array [
           Array [

packages/react/src/components/TextArea/TextArea-test.js

@@ -196,35 +196,81 @@ describe('TextArea', () => {
       ).toEqual(1);
     });
 
-    it('should not render counter with only maxCount prop passed in', () => {
-      render(<TextArea id="testing" labelText="testLabel" maxCount={500} />);
-      // The label and the counter both have the same label class.
-      // The label exists, but not the counter.
-      expect(screen.getByText('testLabel')).toHaveClass(`${prefix}--label`);
-      expect(
-        screen
-          .getByText('testLabel')
-          .closest(`.${prefix}--text-area__label-wrapper`)
-          .getElementsByClassName(`${prefix}--label`).length
-      ).toEqual(1);
+    describe('word counter', () => {
+      it('should not render element with only counterMode prop passed in', () => {
+        render(
+          <TextArea
+            id="wordCounterTestWrapper1"
+            labelText="testLabel"
+            counterMode={'word'}
+          />
+        );
+        expect(
+          screen.getByText('testLabel').closest(`${prefix}--text-area__counter`)
+        ).toEqual(null);
+      });
     });
+  });
 
-    it('should have label and counter disabled', () => {
+  it('should not render counter with only maxCount prop passed in', () => {
+    render(<TextArea id="testing" labelText="testLabel" maxCount={500} />);
+    // The label and the counter both have the same label class.
+    // The label exists, but not the counter.
+    expect(screen.getByText('testLabel')).toHaveClass(`${prefix}--label`);
+    expect(
+      screen
+        .getByText('testLabel')
+        .closest(`.${prefix}--text-area__label-wrapper`)
+        .getElementsByClassName(`${prefix}--label`).length
+    ).toEqual(1);
+  });
+
+  it('should have label and counter disabled', () => {
+    render(
+      <TextArea
+        disabled
+        enableCounter
+        id="testing"
+        labelText="testLabel"
+        maxCount={100}
+      />
+    );
+    expect(screen.getByText('testLabel')).toHaveClass(
+      `${prefix}--label--disabled`
+    );
+    expect(screen.getByText('0/100')).toHaveClass(`${prefix}--label--disabled`);
+  });
+});
+
+describe('events', () => {
+  describe('disabled textarea', () => {
+    it('should not invoke onClick when textarea is clicked', () => {
+      const onClick = jest.fn();
       render(
         <TextArea
           disabled
-          enableCounter
           id="testing"
           labelText="testLabel"
-          maxCount={100}
+          onClick={onClick}
         />
       );
-      expect(screen.getByText('testLabel')).toHaveClass(
-        `${prefix}--label--disabled`
-      );
-      expect(screen.getByText('0/100')).toHaveClass(
-        `${prefix}--label--disabled`
+      userEvent.click(screen.getByLabelText('testLabel'));
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('should not invoke onChange', () => {
+      const onChange = jest.fn();
+      render(
+        <TextArea
+          disabled
+          id="testing"
+          labelText="testLabel"
+          onChange={onChange}
+        />
       );
+      userEvent.click(screen.getByLabelText('testLabel'));
+      userEvent.keyboard('big blue');
+      expect(onChange).not.toHaveBeenCalled();
     });
   });
 

packages/react/src/components/TextArea/TextArea.tsx

@@ -43,7 +43,7 @@ export interface TextAreaProps
   disabled?: boolean;
 
   /**
-   * Specify whether to display the character counter
+   * Specify whether to display the counter
    */
   enableCounter?: boolean;
 
@@ -86,7 +86,7 @@ export interface TextAreaProps
   light?: boolean;
 
   /**
-   * Max character count allowed for the textarea. This is needed in order for enableCounter to display
+   * Max entity count allowed for the textarea. This is needed in order for enableCounter to display
    */
   maxCount?: number;
 
@@ -131,6 +131,11 @@ export interface TextAreaProps
    * Provide the text that is displayed when the control is in warning state
    */
   warnText?: ReactNodeLike;
+
+  /**
+   * Specify the method used for calculating the counter number
+   */
+  counterMode?: string;
 }
 
 const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
@@ -147,6 +152,7 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
     light,
     placeholder,
     enableCounter,
+    counterMode,
     maxCount,
     warn = false,
     warnText,
@@ -155,22 +161,67 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   const prefix = usePrefix();
   const { isFluid } = useContext(FormContext);
   const { defaultValue, value, disabled } = other;
+
   const [textCount, setTextCount] = useState(
-    defaultValue?.toString().length || value?.toString().length || 0
+    defaultValue
+      ? counterMode === 'character'
+        ? defaultValue.toString().length
+        : defaultValue.toString().match(/\w+/g)?.length || 0
+      : value
+      ? counterMode === 'character'
+        ? value.toString().length
+        : value.toString().match(/\w+/g)?.length || 0
+      : 0
   );
   const { current: textAreaInstanceId } = useRef(getInstanceId());
 
   const textareaProps: {
     id: TextAreaProps['id'];
+    onKeyDown: (evt: React.KeyboardEvent) => void;
     onChange: TextAreaProps['onChange'];
     onClick: TextAreaProps['onClick'];
     maxLength?: number;
   } = {
     id,
+    onKeyDown: (evt) => {
+      if (!other.disabled && counterMode === 'word') {
+        const key = evt.which;
+        if (textCount == maxCount && key == 32) {
+          evt.preventDefault();
+        }
+      }
+    },
     onChange: (evt) => {
-      if (!other.disabled && onChange) {
-        setTextCount(evt.target.value?.length);
-        onChange(evt);
+      if (!other.disabled) {
+        if (counterMode == 'character') {
+          setTextCount(evt.target.value.length);
+        } else if (counterMode == 'word') {
+          if (!evt.target.value) {
+            console.log('reset');
+            setTextCount(0);
+            return;
+          }
+
+          if (typeof maxCount !== 'undefined' && textareaRef.current !== null) {
+            const matchedWords = evt.target.value.match(/\w+/g);
+            if (matchedWords && matchedWords.length <= maxCount) {
+              textareaRef.current.removeAttribute('maxLength');
+              setTextCount(matchedWords.length);
+            } else if (matchedWords && matchedWords.length > maxCount) {
+              const first_max = evt.target.value
+                .split(/\s+/)
+                .slice(0, maxCount)
+                .join(' ');
+
+              setTextCount(maxCount);
+              textareaRef.current.value = first_max;
+            }
+            // todo: add handling if no matched words were found
+          }
+        }
+        if (onChange) {
+          onChange(evt);
+        }
       }
     },
     onClick: (evt) => {
@@ -181,9 +232,16 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   };
 
   if (enableCounter) {
-    textareaProps.maxLength = maxCount;
+    // handle different counter mode
+    if (counterMode == 'character') {
+      textareaProps.maxLength = maxCount;
+    }
   }
-  const ariaAnnouncement = useAnnouncer(textCount, maxCount);
+  const ariaAnnouncement = useAnnouncer(
+    textCount,
+    maxCount,
+    counterMode === 'word' ? 'words' : undefined
+  );
 
   const labelClasses = classNames(`${prefix}--label`, {
     [`${prefix}--visually-hidden`]: hideLabel && !isFluid,
@@ -201,7 +259,9 @@ const TextArea = React.forwardRef((props: TextAreaProps, forwardRef) => {
   });
 
   const counter =
-    enableCounter && maxCount ? (
+    enableCounter &&
+    maxCount &&
+    (counterMode === 'character' || counterMode === 'word') ? (
       <div className={counterClasses}>{`${textCount}/${maxCount}`}</div>
     ) : null;
 
@@ -331,6 +391,11 @@ TextArea.propTypes = {
    */
   cols: PropTypes.number,
 
+  /**
+   * Specify the method used for calculating the counter number
+   */
+  counterMode: PropTypes.oneOf(['character', 'word']),
+
   /**
    * Optionally provide the default value of the `<textarea>`
    */
@@ -342,7 +407,7 @@ TextArea.propTypes = {
   disabled: PropTypes.bool,
 
   /**
-   * Specify whether to display the character counter
+   * Specify whether to display the counter
    */
   enableCounter: PropTypes.bool,
 
@@ -388,7 +453,7 @@ TextArea.propTypes = {
   ),
 
   /**
-   * Max character count allowed for the textarea. This is needed in order for enableCounter to display
+   * Max entity count allowed for the textarea. This is needed in order for enableCounter to display
    */
   maxCount: PropTypes.number,
 
@@ -446,6 +511,7 @@ TextArea.defaultProps = {
   helperText: '',
   enableCounter: false,
   maxCount: undefined,
+  counterMode: 'character',
   warn: false,
   warnText: '',
 };