feat: New fluid text area web component (#20420)

* feat: new fluid text area web component

* fix: docs and test cases

* fix: warn and invalid states

* fix: docs and test

* fix: test cases

* fix: helper text test

* fix: test cases

* fix: story fix

---------

Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

Author: riddhybansal

e2e/components/FluidTextArea/FluidTextArea-test.avt.e2e.js

@@ -35,16 +35,16 @@ test.describe('@avt FluidTextArea', () => {
     );
   });
 
-  test('@avt-advanced-states default-with-tooltip', async ({ page }) => {
+  test('@avt-advanced-states default-with-toggletip', async ({ page }) => {
     await visitStory(page, {
       component: 'FluidTextArea',
-      id: 'components-fluid-components-fluidtextarea--default-with-tooltip',
+      id: 'components-fluid-components-fluidtextarea--default-with-toggletip',
       globals: {
         theme: 'white',
       },
     });
     await expect(page).toHaveNoACViolations(
-      'FluidTextArea-default-with-tooltip'
+      'FluidTextArea-default-with-toggletip'
     );
   });
 
@@ -80,17 +80,17 @@ test.describe('@avt FluidTextArea', () => {
     await expect(page).toHaveNoACViolations('FluidTextArea default');
   });
 
-  test('@avt-keyboard-nav FluidTextArea with tooltip', async ({ page }) => {
+  test('@avt-keyboard-nav FluidTextArea with toggletip', async ({ page }) => {
     await visitStory(page, {
       component: 'TextArea',
-      id: 'components-fluid-components-fluidtextarea--default-with-tooltip',
+      id: 'components-fluid-components-fluidtextarea--default-with-toggletip',
       globals: {
         theme: 'white',
       },
     });
     await expect(page.getByText('Text Area label')).toBeVisible();
 
-    // Checking tooltip
+    // Checking toggletip
     await page.keyboard.press('Tab');
     await expect(page.getByLabel('Show information')).toBeFocused();
     await page.keyboard.press('Enter');
@@ -106,6 +106,6 @@ test.describe('@avt FluidTextArea', () => {
     // Writting a word to check functionality
     await textArea.fill('test');
     await expect(textArea).toHaveValue('test');
-    await expect(page).toHaveNoACViolations('FluidTextArea with tooltip');
+    await expect(page).toHaveNoACViolations('FluidTextArea with toggletip');
   });
 });

packages/react/src/components/FluidTextArea/FluidTextArea.mdx

@@ -15,7 +15,7 @@ import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';
 
 - [Overview](#overview)
   - [Skeleton](#skeleton)
-  - [Default With Tooltip](#default-with-tooltip)
+  - [Default With Toggletip](#default-with-toggletip)
   - [Default With Layers](#default-with-layers)
 - [Accessibility Considerations](#accessibility-considerations)
   - [Accessible Name](#accessible-name)
@@ -48,14 +48,14 @@ import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';
   ]}
 />
 
-### Default With Tooltip
+### Default With Toggletip
 
 <Canvas
-  of={FluidTextAreaStories.DefaultWithTooltip}
+  of={FluidTextAreaStories.DefaultWithToggletip}
   additionalActions={[
     {
       title: 'Open in Stackblitz',
-      onClick: () => stackblitzPrefillConfig(FluidTextAreaStories.DefaultWithTooltip),
+      onClick: () => stackblitzPrefillConfig(FluidTextAreaStories.DefaultWithToggletip),
     },
   ]}
 />

packages/react/src/components/FluidTextArea/FluidTextArea.stories.js

@@ -160,7 +160,7 @@ const ToggleTip = (
   </>
 );
 
-export const DefaultWithTooltip = () => (
+export const DefaultWithToggletip = () => (
   <FluidTextArea labelText={ToggleTip} placeholder="Placeholder text" />
 );
 

packages/web-components/src/components/fluid-textarea/__tests__/fluid-textarea-test.js

@@ -0,0 +1,212 @@
+/**
+ * Copyright IBM Corp. 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import '@carbon/web-components/es/components/fluid-textarea/index.js';
+import { html, fixture, expect, oneEvent } from '@open-wc/testing';
+
+describe('cds-fluid-textarea', () => {
+  it('should render correctly with label', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea
+        label="Textarea label"
+        helper-text="Helper text"></cds-fluid-textarea>
+    `);
+
+    const label = el.shadowRoot.querySelector('label');
+
+    expect(label).to.exist;
+    expect(label.textContent).to.include('Textarea label');
+  });
+
+  it('should reflect value to the textarea', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea value="Initial content"></cds-fluid-textarea>
+    `);
+
+    const textarea = el.shadowRoot.querySelector('textarea');
+    expect(textarea.value).to.equal('Initial content');
+  });
+
+  it('should emit input event and update value', async () => {
+    const el = await fixture(html`<cds-fluid-textarea></cds-fluid-textarea>`);
+    const textarea = el.shadowRoot.querySelector('textarea');
+    textarea.value = 'Updated content';
+    textarea.dispatchEvent(new Event('input', { bubbles: true }));
+
+    await el.updateComplete;
+    expect(el.value).to.equal('Updated content');
+  });
+
+  it('should support readonly and disabled attributes', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea readonly disabled></cds-fluid-textarea>
+    `);
+
+    const textarea = el.shadowRoot.querySelector('textarea');
+    expect(textarea.readOnly).to.be.true;
+    expect(textarea.disabled).to.be.true;
+  });
+
+  it('should show invalid text when invalid is set', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea
+        invalid
+        invalid-text="Error occurred"></cds-fluid-textarea>
+    `);
+
+    const error = el.shadowRoot.querySelector('.cds--form-requirement');
+    expect(error.textContent).to.include('Error occurred');
+    expect(el.hasAttribute('invalid')).to.be.true;
+  });
+
+  it('should show warning text when warn is set', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea
+        warn
+        warn-text="This is a warning"></cds-fluid-textarea>
+    `);
+
+    const warning = el.shadowRoot.querySelector('.cds--form-requirement');
+    expect(warning.textContent).to.include('This is a warning');
+    expect(el.hasAttribute('warn')).to.be.true;
+  });
+
+  it('should apply hide-label and visually hide the label', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea label="Hidden label" hide-label></cds-fluid-textarea>
+    `);
+    const label = el.shadowRoot.querySelector('label');
+    expect(label.classList.contains('cds--visually-hidden')).to.be.true;
+  });
+
+  it('should reflect cols and rows attributes', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea cols="50" rows="10"></cds-fluid-textarea>
+    `);
+    const textarea = el.shadowRoot.querySelector('textarea');
+    expect(textarea.getAttribute('cols')).to.equal('50');
+    expect(textarea.getAttribute('rows')).to.equal('10');
+  });
+
+  it('should accept pattern and required attributes', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea pattern="[A-Za-z]+" required></cds-fluid-textarea>
+    `);
+    const textarea = el.shadowRoot.querySelector('textarea');
+    expect(textarea.getAttribute('pattern')).to.equal('[A-Za-z]+');
+    expect(textarea.hasAttribute('required')).to.be.true;
+  });
+
+  it('should forward data-* attributes', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea data-testid="textarea-id"></cds-fluid-textarea>
+    `);
+    expect(el.getAttribute('data-testid')).to.equal('textarea-id');
+  });
+
+  it('should support skeleton variant', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea-skeleton></cds-fluid-textarea-skeleton>
+    `);
+    expect(el).to.exist;
+    const skeleton = el.shadowRoot.querySelector('.cds--skeleton');
+    expect(skeleton).to.exist;
+  });
+
+  it('should be accessible', async () => {
+    const el = await fixture(html`
+      <cds-fluid-textarea
+        label="Label"
+        helper-text="Help"
+        value="value"></cds-fluid-textarea>
+    `);
+    await expect(el).to.be.accessible();
+  });
+
+  // Additional parity tests with React
+
+  describe('counter mode behaviors', () => {
+    // Test for switching counter mode from "word" to "character"
+    it('should apply maxlength only in character mode', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea
+          enable-counter
+          counter-mode="character"
+          max-count="100"></cds-fluid-textarea>
+      `);
+      const textarea = el.shadowRoot.querySelector('textarea');
+      expect(textarea.getAttribute('maxlength')).to.equal('100');
+    });
+
+    // Test for switching counter mode from "word" to "character"
+    it('should remove maxlength when switching to word mode', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea
+          enable-counter
+          counter-mode="character"
+          max-count="100"></cds-fluid-textarea>
+      `);
+      el.counterMode = 'word';
+      await el.updateComplete;
+      const textarea = el.shadowRoot.querySelector('textarea');
+      expect(textarea.hasAttribute('maxlength')).to.be.false;
+    });
+
+    // Test for switching back to character mode
+    it('should add maxlength when switching back to character mode', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea
+          enable-counter
+          counter-mode="word"
+          max-count="100"></cds-fluid-textarea>
+      `);
+      el.counterMode = 'character';
+      await el.updateComplete;
+      const textarea = el.shadowRoot.querySelector('textarea');
+      expect(textarea.getAttribute('maxlength')).to.equal('100');
+    });
+  });
+
+  // Slot support tests (label-text, helper-text, invalid-text, warn-text)
+  describe('slot support', () => {
+    it('renders slotted label-text', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea>
+          <span slot="label-text">Slotted Label</span>
+        </cds-fluid-textarea>
+      `);
+      await el.updateComplete;
+      const slot = el.shadowRoot.querySelector('slot[name="label-text"]');
+      const content = slot.assignedNodes({ flatten: true })[0];
+      expect(content.textContent.trim()).to.equal('Slotted Label');
+    });
+
+    it('renders slotted invalid-text', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea invalid>
+          <span slot="invalid-text">Slotted Invalid</span>
+        </cds-fluid-textarea>
+      `);
+      await el.updateComplete;
+      const slot = el.shadowRoot.querySelector('slot[name="invalid-text"]');
+      const content = slot.assignedNodes({ flatten: true })[0];
+      expect(content.textContent.trim()).to.equal('Slotted Invalid');
+    });
+
+    it('renders slotted warn-text', async () => {
+      const el = await fixture(html`
+        <cds-fluid-textarea warn>
+          <span slot="warn-text">Slotted Warning</span>
+        </cds-fluid-textarea>
+      `);
+      await el.updateComplete;
+      const slot = el.shadowRoot.querySelector('slot[name="warn-text"]');
+      const content = slot.assignedNodes({ flatten: true })[0];
+      expect(content.textContent.trim()).to.equal('Slotted Warning');
+    });
+  });
+});

packages/web-components/src/components/fluid-textarea/fluid-textarea-skeleton.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright IBM Corp.2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { prefix } from '../../globals/settings';
+import { html } from 'lit';
+import { carbonElement as customElement } from '../../globals/decorators/carbon-element';
+import CDSTextareaSkeleton from '../textarea/textarea-skeleton';
+import styles from './fluid-textarea.scss?lit';
+
+/**
+ * Fluid text area input.
+ *
+ * @element cds-fluid-textarea
+ */
+@customElement(`${prefix}-fluid-textarea-skeleton`)
+class CDSFluidTextareaSkeleton extends CDSTextareaSkeleton {
+  render() {
+    return html`
+      <div class="${prefix}--text-area--fluid__skeleton ${prefix}--form-item">
+        ${super.render()}
+      </div>
+    `;
+  }
+
+  static styles = [CDSTextareaSkeleton.styles, styles];
+}
+
+export default CDSFluidTextareaSkeleton;

packages/web-components/src/components/fluid-textarea/fluid-textarea.mdx

@@ -0,0 +1,44 @@
+import { ArgTypes, Canvas, Markdown, Meta } from '@storybook/addon-docs/blocks';
+import { cdnJs } from '../../globals/internal/storybook-cdn';
+import * as FluidTextAreaStories from './fluid-textarea.stories';
+
+<Meta of={FluidTextAreaStories} />
+
+# Text Area
+
+[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/web-components/src/components/fluid-textarea)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Skeleton](#skeleton)
+- [Default With Tooltip](#default-with-tooltip)
+- [Component API](#component-api)
+- [CDN](#cdn)
+- [Feedback](#feedback)
+
+## Overview
+
+<Canvas of={FluidTextAreaStories.Default} />
+
+## Skeleton
+
+<Canvas of={FluidTextAreaStories.Skeleton} />
+
+## Default With Toggletip
+
+<Canvas of={FluidTextAreaStories.DefaultWithToggletip} />
+
+## Component API
+
+## `cds-fluid-textarea`
+
+<ArgTypes of="cds-textarea" />
+
+<Markdown>{`${cdnJs({ components: ['fluid-textarea'] })}`}</Markdown>
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions on Slack,
+or updating this file on
+[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/web-components/src/components/fluid-textarea/fluid-textarea.mdx).

packages/web-components/src/components/fluid-textarea/fluid-textarea.scss

@@ -0,0 +1,16 @@
+/**
+ * Copyright IBM Corp.2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+$css--plex: true !default;
+@use '@carbon/styles/scss/config' as *;
+@use '@carbon/styles/scss/components/fluid-text-area/index';
+@use '@carbon/styles/scss/layout' as *;
+@use '@carbon/styles/scss/spacing' as *;
+
+:host(#{$prefix}-fluid-textarea) {
+  @include emit-layout-tokens();
+}