@transferwise/components 0.0.0-experimental-369191f → 0.0.0-experimental-77bcd0d

package/src/field/Field.less

@@ -1,16 +1,30 @@
 .np-field {
-  &-control,
-  &__prompt {
+  &-control {
     margin-top: var(--size-4);
   }
 
+  &-validation {
+    display: flex;
+    align-items: flex-start;
+    margin-top: var(--size-4);
+    gap: var(--size-8);
+  }
+
+  &-textarea-char-counter {
+    min-width: 55px;
+    text-align: right;
+    margin-left: auto;
+    padding: var(--size-4) 0;
+    color: var(--color-content-tertiary);
+  }
+
   // @FIXME space between individual fields should be 24px, while some older inputs
   //        inject extraneous space.
   .form-group--typeahead[class],
   .np-checkbox-label[class] {
     margin-bottom: 0;
   }
-  &:has(.wds-radio-group) &__prompt {
+  &:has(.wds-radio-group) &-validation {
     margin-top: var(--size-12);
   }
 }

package/src/field/Field.messages.ts

@@ -0,0 +1,8 @@
+import { defineMessages } from 'react-intl';
+
+export default defineMessages({
+  characterCount: {
+    id: 'neptune.Field.characterCount',
+    defaultMessage: '{current} of {max} characters used',
+  },
+});

package/src/field/Field.story.tsx

@@ -84,7 +84,11 @@ export const Basic = (args: FieldProps) => {
           messageIconLabel={args.messageIconLabel}
           messageLoading={args.messageLoading}
         >
-          <TextArea />
+          <TextArea
+            maxLength={200}
+            value={value}
+            onChange={({ target }) => setValue(target.value)}
+          />
         </Field>
 
         <Field

package/src/field/Field.test.tsx

@@ -1,5 +1,6 @@
 import Info from '../info/Info';
 import { Input } from '../inputs/Input';
+import { TextArea } from '../inputs/TextArea';
 import { mockMatchMedia, render, screen, userEvent } from '../test-utils';
 
 import { Field } from './Field';
@@ -163,4 +164,93 @@ describe('Field', () => {
     expect(screen.getByTestId('InlinePrompt_ProcessIndicator')).toBeInTheDocument();
     expect(screen.getByText('Processing your request')).toBeInTheDocument();
   });
+
+  describe('TextArea character count', () => {
+    it('renders counter when TextArea has maxLength', () => {
+      render(
+        <Field label="Message">
+          <TextArea maxLength={200} value="hello" onChange={() => {}} />
+        </Field>,
+      );
+
+      expect(screen.getByText('5/200')).toBeInTheDocument();
+    });
+
+    it('does not render counter when TextArea has no maxLength', () => {
+      render(
+        <Field label="Message">
+          <TextArea value="hello" onChange={() => {}} />
+        </Field>,
+      );
+
+      expect(screen.queryByText(/\/\d+/)).not.toBeInTheDocument();
+    });
+
+    it('includes counter id in aria-describedby of the textarea', () => {
+      render(
+        <Field label="Message">
+          <TextArea maxLength={200} value="hello" onChange={() => {}} />
+        </Field>,
+      );
+
+      const textarea = screen.getByRole('textbox');
+      const counter = screen.getByText('5/200');
+      expect(textarea).toHaveAttribute('aria-describedby', expect.stringContaining(counter.id));
+    });
+
+    it('does not have role=status below 80% threshold', () => {
+      render(
+        <Field label="Message">
+          <TextArea maxLength={200} value="short" onChange={() => {}} />
+        </Field>,
+      );
+
+      const counter = screen.getByText('5/200');
+      expect(counter).not.toHaveAttribute('role');
+      expect(counter).not.toHaveAttribute('aria-live');
+    });
+
+    it('has role=status and aria-live=polite at 80% threshold', () => {
+      const value = 'x'.repeat(160);
+      render(
+        <Field label="Message">
+          <TextArea maxLength={200} value={value} onChange={() => {}} />
+        </Field>,
+      );
+
+      const counter = screen.getByText('160/200');
+      expect(counter).toHaveAttribute('role', 'status');
+      expect(counter).toHaveAttribute('aria-live', 'polite');
+      expect(counter).toHaveAttribute('aria-atomic', 'true');
+    });
+
+    it('updates counter when text changes', () => {
+      const { rerender } = render(
+        <Field label="Message">
+          <TextArea maxLength={200} value="hi" onChange={() => {}} />
+        </Field>,
+      );
+
+      expect(screen.getByText('2/200')).toBeInTheDocument();
+
+      rerender(
+        <Field label="Message">
+          <TextArea maxLength={200} value="hello world" onChange={() => {}} />
+        </Field>,
+      );
+
+      expect(screen.getByText('11/200')).toBeInTheDocument();
+    });
+
+    it('provides accessible aria-label on the counter', () => {
+      render(
+        <Field label="Message">
+          <TextArea maxLength={200} value="hello" onChange={() => {}} />
+        </Field>,
+      );
+
+      const counter = screen.getByText('5/200');
+      expect(counter).toHaveAttribute('aria-label', '5 of 200 characters used');
+    });
+  });
 });

package/src/field/Field.tsx

@@ -1,9 +1,14 @@
 import { clsx } from 'clsx';
-import { useId, useRef } from 'react';
+import { useCallback, useId, useRef, useState } from 'react';
+import { useIntl } from 'react-intl';
 
+import Body from '../body';
 import { Sentiment } from '../common';
+import messages from './Field.messages';
 import { InlinePrompt, type InlinePromptProps } from '../prompt';
 import {
+  TextareaCharacterCountProvider,
+  type TextareaCharacterCountState,
   FieldLabelContextProvider,
   InputDescribedByProvider,
   InputIdContextProvider,
@@ -54,6 +59,7 @@ export const Field = ({
   children,
   ...props
 }: FieldProps) => {
+  const { formatMessage } = useIntl();
   const labelRef = useRef<HTMLLabelElement>(null);
   const sentiment = props.error ? Sentiment.NEGATIVE : propType;
   const message = propMessage || props.error;
@@ -66,6 +72,18 @@ export const Field = ({
 
   const messageId = useId();
   const descriptionId = useId();
+  const textareaCharCounterId = useId();
+
+  const [textareaCharacterCount, setTextareaCharacterCount] =
+    useState<TextareaCharacterCountState>(null);
+  const handleTextareaCharacterCount = useCallback(
+    (state: TextareaCharacterCountState) => setTextareaCharacterCount(state),
+    [],
+  );
+
+  const isNearCharLimit =
+    textareaCharacterCount != null &&
+    textareaCharacterCount.current >= textareaCharacterCount.max * 0.8;
 
   /**
    * form control can have multiple messages to describe it,
@@ -79,6 +97,9 @@ export const Field = ({
     if (message) {
       messageIds.push(messageId);
     }
+    if (textareaCharacterCount) {
+      messageIds.push(textareaCharCounterId);
+    }
     return messageIds.length > 0 ? messageIds.join(' ') : undefined;
   }
 
@@ -87,43 +108,69 @@ export const Field = ({
       <InputIdContextProvider value={inputId}>
         <InputDescribedByProvider value={ariaDescribedbyByIds()}>
           <InputInvalidProvider value={hasError}>
-            <div
-              className={clsx(
-                'np-field form-group d-block',
-                {
-                  'has-success': sentiment === Sentiment.POSITIVE,
-                  'has-warning': sentiment === Sentiment.WARNING,
-                  'has-error': hasError,
-                  'has-info': sentiment === Sentiment.NEUTRAL,
-                },
-                className,
-              )}
-            >
-              {label != null ? (
-                <>
-                  <Label ref={labelRef} id={labelId} htmlFor={inputId}>
-                    {required ? label : <Label.Optional>{label}</Label.Optional>}
-                  </Label>
-                  <Label.Description id={descriptionId}>{description}</Label.Description>
-                  <div className="np-field-control">{children}</div>
-                </>
-              ) : (
-                children
-              )}
+            <TextareaCharacterCountProvider value={handleTextareaCharacterCount}>
+              <div
+                className={clsx(
+                  'np-field form-group d-block',
+                  {
+                    'has-success': sentiment === Sentiment.POSITIVE,
+                    'has-warning': sentiment === Sentiment.WARNING,
+                    'has-error': hasError,
+                    'has-info': sentiment === Sentiment.NEUTRAL,
+                  },
+                  className,
+                )}
+              >
+                {label != null ? (
+                  <>
+                    <Label ref={labelRef} id={labelId} htmlFor={inputId}>
+                      {required ? label : <Label.Optional>{label}</Label.Optional>}
+                    </Label>
+                    <Label.Description id={descriptionId}>{description}</Label.Description>
+                    <div className="np-field-control">{children}</div>
+                  </>
+                ) : (
+                  children
+                )}
 
-              {message && (
-                <InlinePrompt
-                  sentiment={sentiment}
-                  id={messageId}
-                  mediaLabel={messageIconLabel}
-                  className="np-field__prompt"
-                  loading={messageLoading}
-                  width="full"
-                >
-                  {message}
-                </InlinePrompt>
-              )}
-            </div>
+                {(message || textareaCharacterCount) && (
+                  <div className="np-field-validation">
+                    {message && (
+                      <InlinePrompt
+                        sentiment={sentiment}
+                        id={messageId}
+                        mediaLabel={messageIconLabel}
+                        className="np-field__prompt"
+                        loading={messageLoading}
+                        width="full"
+                      >
+                        {message}
+                      </InlinePrompt>
+                    )}
+                    {textareaCharacterCount && (
+                      <Body
+                        as="span"
+                        id={textareaCharCounterId}
+                        {...(isNearCharLimit
+                          ? {
+                              role: 'status' as const,
+                              'aria-live': 'polite' as const,
+                              'aria-atomic': 'true' as const,
+                            }
+                          : {})}
+                        aria-label={formatMessage(messages.characterCount, {
+                          current: textareaCharacterCount.current,
+                          max: textareaCharacterCount.max,
+                        })}
+                        className="np-field-textarea-char-counter"
+                      >
+                        {textareaCharacterCount.current}/{textareaCharacterCount.max}
+                      </Body>
+                    )}
+                  </div>
+                )}
+              </div>
+            </TextareaCharacterCountProvider>
           </InputInvalidProvider>
         </InputDescribedByProvider>
       </InputIdContextProvider>

package/src/i18n/en.json

@@ -20,6 +20,7 @@
   "neptune.Expander.expandAriaLabel": "Expand",
   "neptune.ExpressiveMoneyInput.currency.search.placeholder": "Type a currency / country",
   "neptune.ExpressiveMoneyInput.currency.select.currency": "Select currency",
+  "neptune.Field.characterCount": "{current} of {max} characters used",
   "neptune.FlowNavigation.back": "back to previous step",
   "neptune.Info.ariaLabel": "More information",
   "neptune.Label.optional": "(Optional)",

package/src/inputs/TextArea.story.tsx

@@ -0,0 +1,56 @@
+import { useState } from 'react';
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+
+import { Field } from '../field/Field';
+import { Sentiment } from '../common';
+import { TextArea } from './TextArea';
+
+const meta: Meta<typeof TextArea> = {
+  title: 'Forms/TextArea',
+  component: TextArea,
+};
+
+export default meta;
+type Story = StoryObj<typeof TextArea>;
+
+export const Basic: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={10} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<Field label="Message" required={false}>
+  <TextArea
+    maxLength={200}
+    value={value}
+    onChange={({ target }) => setValue(target.value)}
+  />
+</Field>`,
+      },
+    },
+  },
+};
+
+export const WithError: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field
+        label="Message"
+        required={false}
+        sentiment={Sentiment.NEGATIVE}
+        message="You have exceeded the character limit"
+      >
+        <TextArea maxLength={200} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+};

package/src/inputs/TextArea.test.story.tsx

@@ -0,0 +1,129 @@
+import { useState } from 'react';
+import { userEvent, within } from 'storybook/test';
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+
+import { Field } from '../field/Field';
+import { TextArea } from './TextArea';
+
+const meta: Meta<typeof TextArea> = {
+  title: 'Forms/TextArea/Tests',
+  component: TextArea,
+  tags: ['!autodocs', '!manifest'],
+};
+
+export default meta;
+type Story = StoryObj<typeof TextArea>;
+
+export const AsciiCharacters: Story = {
+  name: 'maxLength with ASCII characters (10/10)',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={10} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.type(canvas.getByRole('textbox'), '0123456789');
+  },
+};
+
+export const EmojiCharacters: Story = {
+  name: 'maxLength with emoji characters (grapheme clusters)',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={10} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByRole('textbox');
+    await userEvent.click(textarea);
+    await userEvent.paste('🐱💕🐱💕');
+  },
+};
+
+export const EmojiAtLimit: Story = {
+  name: 'maxLength enforcement stops input at grapheme limit',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={10} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByRole('textbox');
+    await userEvent.click(textarea);
+    await userEvent.paste('🐱💕🐱💕🐱💕🐱💕🐱💕🐱💕🐱💕');
+  },
+};
+
+export const CJKCharacters: Story = {
+  name: 'maxLength with CJK surrogate pair characters',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={10} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByRole('textbox');
+    await userEvent.click(textarea);
+    await userEvent.paste('吉𣘺吉𣘺吉𣘺吉𣘺吉𣘺吉𣘺');
+  },
+};
+
+export const EmojiTypingBlocked: Story = {
+  name: 'typing emoji beyond limit is blocked',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={3} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByRole('textbox');
+    await userEvent.click(textarea);
+    await userEvent.paste('🐱💕');
+    await userEvent.paste('🎉🎉🎉');
+  },
+};
+
+export const CJKTypingBlocked: Story = {
+  name: 'typing CJK surrogates beyond limit is blocked',
+  render: () => {
+    const [value, setValue] = useState('');
+
+    return (
+      <Field label="Message" required={false}>
+        <TextArea maxLength={3} value={value} onChange={({ target }) => setValue(target.value)} />
+      </Field>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByRole('textbox');
+    await userEvent.click(textarea);
+    await userEvent.paste('吉𣘺');
+    await userEvent.paste('吉𣘺吉𣘺吉𣘺');
+  },
+};

package/src/inputs/TextArea.tsx

@@ -1,9 +1,9 @@
 import { clsx } from 'clsx';
-import { forwardRef } from 'react';
+import { forwardRef, useCallback } from 'react';
 
 import { Merge } from '../utils';
 import { inputClassNameBase } from './_common';
-import { useInputAttributes } from './contexts';
+import { useTextareaCharacterCount, useInputAttributes } from './contexts';
 
 export interface TextAreaProps extends Merge<
   React.ComponentPropsWithRef<'textarea'>,
@@ -13,17 +13,68 @@ export interface TextAreaProps extends Merge<
 > {}
 
 export const TextArea = forwardRef(function TextArea(
-  { className, ...restProps }: TextAreaProps,
+  { className, maxLength, onChange, ...restProps }: TextAreaProps,
   reference: React.ForwardedRef<HTMLTextAreaElement | null>,
 ) {
   const inputAttributes = useInputAttributes();
+  const value = restProps.value ?? restProps.defaultValue ?? '';
+  const currentLength = getGraphemeLength(typeof value === 'string' ? value : String(value));
+
+  useTextareaCharacterCount(currentLength, maxLength);
+
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      if (maxLength != null) {
+        const truncated = truncateToGraphemes(e.target.value, maxLength);
+        if (truncated !== e.target.value) {
+          Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set?.call(
+            e.target,
+            truncated,
+          );
+        }
+      }
+      onChange?.(e);
+    },
+    [maxLength, onChange],
+  );
 
   return (
     <textarea
       ref={reference}
       className={clsx(className, inputClassNameBase(), 'np-text-area')}
+      onChange={handleChange}
       {...inputAttributes}
       {...restProps}
     />
   );
 });
+
+const segmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : undefined;
+
+function getGraphemeLength(str: string): number {
+  if (segmenter) {
+    let count = 0;
+    for (const _ of segmenter.segment(str)) {
+      count += 1;
+    }
+    return count;
+  }
+  return Array.from(str).length;
+}
+
+function truncateToGraphemes(str: string, max: number): string {
+  if (segmenter) {
+    let result = '';
+    let count = 0;
+    for (const { segment } of segmenter.segment(str)) {
+      if (count >= max) break;
+      result += segment;
+      count += 1;
+    }
+    return result;
+  }
+  return Array.from(str).slice(0, max).join('');
+}

package/src/inputs/contexts.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext } from 'react';
+import { createContext, useContext, useEffect } from 'react';
 
 type FieldLabelContextType = {
   id?: string;
@@ -36,6 +36,23 @@ export function useFieldLabelRef() {
   return useContext(FieldLabelContext)?.ref;
 }
 
+export type TextareaCharacterCountState = { current: number; max: number } | null;
+
+const TextareaCharacterCountContext = createContext<
+  ((state: TextareaCharacterCountState) => void) | undefined
+>(undefined);
+export const TextareaCharacterCountProvider = TextareaCharacterCountContext.Provider;
+
+export function useTextareaCharacterCount(current: number, max: number | undefined) {
+  const setCharacterCount = useContext(TextareaCharacterCountContext);
+  useEffect(() => {
+    if (setCharacterCount && max != null) {
+      setCharacterCount({ current, max });
+      return () => setCharacterCount(null);
+    }
+  }, [setCharacterCount, current, max]);
+}
+
 export interface WithInputAttributesProps {
   inputAttributes: ReturnType<typeof useInputAttributes>;
 }