ui-react(fix): Update ShowPasswordButton (#2323)

* Update ShowPasswordButton to use role=“switch” and add additional SR context

* update types and PasswordField

* updated tests

* Create poor-pans-chew.md

* updated props table, marked hidePasswordButtonLabel as deprecated, updated variable names

* adding passwordIsHiddenLabel and passwordIsShownLabel props

* update tests

* update docs

* update type descriptions

* update props table

* Update .changeset/poor-pans-chew.md

Co-authored-by: Heather Buchel <[email protected]>

* update changeset

Co-authored-by: Joe Buono <[email protected]>
Co-authored-by: Heather Buchel <[email protected]>

Author: 3 people

.changeset/poor-pans-chew.md

@@ -0,0 +1,9 @@
+---
+"@aws-amplify/ui-react": patch
+---
+
+ui-react(fix): Update ShowPasswordButton to use role=“switch” and add additional screen reader context
+
+- Keep consistent aria-label “Show password”
+- Add a visually hidden aria-live region (polite) that updates based on the ShowPasswordButton checked state
+- Add `passwordIsHiddenLabel` and `passwordIsShownLabel` props for screen readers

docs/src/pages/[platform]/components/passwordfield/examples/ShowPasswordButtonExample.tsx

@@ -0,0 +1,12 @@
+import { PasswordField } from '@aws-amplify/ui-react';
+
+export const ShowPasswordButtonExample = () => {
+  return (
+    <PasswordField
+      label="Password"
+      showPasswordButtonLabel="Toggle password shown/hidden"
+      passwordIsHiddenLabel="Your password is hidden"
+      passwordIsShownLabel="Your password is shown"
+    />
+  );
+};

docs/src/pages/[platform]/components/passwordfield/examples/index.ts

@@ -9,6 +9,7 @@ export { MaxLengthExample } from './MaxLengthExample';
 export { PasswordFieldStyledPropsExample } from './PasswordFieldStyledPropsExample';
 export { RefExample } from './refs';
 export { RequiredPasswordFieldExample } from './RequiredPasswordFieldExample';
+export { ShowPasswordButtonExample } from './ShowPasswordButtonExample';
 export { SignUpFormExample } from './SignUpFormExample';
 export { SizeExample } from './SizeExample';
 export { PasswordFieldThemeExample } from './PasswordFieldThemeExample';

docs/src/pages/[platform]/components/passwordfield/props-table.mdx

@@ -116,7 +116,7 @@ boolean
 string
 ```
 </TableCell>
-      <TableCell className="props-table__tr-description">Set the &#96;aria-label&#96; for hide password button Default: "Hide password"</TableCell>
+      <TableCell className="props-table__tr-description">The hidePasswordButtonLabel prop is no longer in use, since the aria-label is now consistent between state changes. Set the &#96;aria-label&#96; for hide password button Default: "Hide password"</TableCell>
     </TableRow>
 
     <TableRow>
@@ -249,6 +249,26 @@ React.ReactNode
       <TableCell className="props-table__tr-description">Component(s) to show before input</TableCell>
     </TableRow>
 
+    <TableRow>
+      <TableCell className="props-table__tr-name">passwordIsHiddenLabel</TableCell>
+      <TableCell>
+```jsx
+string
+```
+</TableCell>
+      <TableCell className="props-table__tr-description">Sets the text read by screen readers when the password is hidden Default: "Password is hidden"</TableCell>
+    </TableRow>
+
+    <TableRow>
+      <TableCell className="props-table__tr-name">passwordIsShownLabel</TableCell>
+      <TableCell>
+```jsx
+string
+```
+</TableCell>
+      <TableCell className="props-table__tr-description">Sets the text read by screen readers when the password is shown Default: "Password is shown"</TableCell>
+    </TableRow>
+
     <TableRow>
       <TableCell className="props-table__tr-name">placeholder</TableCell>
       <TableCell>

docs/src/pages/[platform]/components/passwordfield/react.mdx

@@ -24,11 +24,12 @@ import {
   LoginFormExample,
   MaxLengthExample,
   PasswordFieldStyledPropsExample,
+  PasswordFieldThemeExample,
   RefExample,
   RequiredPasswordFieldExample,
+  ShowPasswordButtonExample,
   SignUpFormExample,
   SizeExample,
-  PasswordFieldThemeExample,
   ValidationErrorExample,
   VariationExample,
 } from './examples';
@@ -128,6 +129,27 @@ _Change password example: `current-password` and `new-password`_
   </ExampleCode>
 </Example>
 
+#### ShowPasswordButton
+
+The ShowPasswordButton renders a `<button>` element with `role="switch"`. Its `aria-checked` attribute is set to `false` when the password is hidden, and `true` when the password is shown. 
+
+There are several optional props for customizing the accessibility of the ShowPasswordButton:
+
+- `showPasswordButtonLabel`: Sets the `aria-label` for the ShowPasswordButton (defaults to `"Show password"`)
+- `passwordIsHiddenLabel`: Sets the text read by screen readers when the password is hidden (defaults to `"Password is hidden"`)
+- `passwordIsShownLabel`: Sets the text read by screen readers when the password is shown (defaults to `"Password is shown"`)
+
+<Example>
+  <ShowPasswordButtonExample />
+  <ExampleCode>
+
+```jsx file=./examples/ShowPasswordButtonExample.tsx
+
+```
+
+  </ExampleCode>
+</Example>
+
 ### Sizes
 
 Use the `size` prop to change the visual size of the PasswordField. Three sizes are available: `small`, (default), and `large`.

packages/react/src/primitives/PasswordField/PasswordField.tsx

@@ -12,7 +12,8 @@ const PasswordFieldPrimitive: Primitive<PasswordFieldProps, 'input'> = (
     label,
     className,
     hideShowPassword = false,
-    hidePasswordButtonLabel,
+    passwordIsHiddenLabel,
+    passwordIsShownLabel,
     showPasswordButtonLabel,
     showPasswordButtonRef,
     size,
@@ -39,9 +40,10 @@ const PasswordFieldPrimitive: Primitive<PasswordFieldProps, 'input'> = (
           <ShowPasswordButton
             fieldType={type}
             onClick={showPasswordOnClick}
+            passwordIsHiddenLabel={passwordIsHiddenLabel}
+            passwordIsShownLabel={passwordIsShownLabel}
             ref={showPasswordButtonRef}
             size={size}
-            hidePasswordButtonLabel={hidePasswordButtonLabel}
             showPasswordButtonLabel={showPasswordButtonLabel}
           />
         )

packages/react/src/primitives/PasswordField/ShowPasswordButton.tsx

@@ -1,37 +1,43 @@
 import * as React from 'react';
 
 import { Button } from '../Button';
+import { VisuallyHidden } from '../VisuallyHidden';
 import { ComponentClassNames, ComponentText } from '../shared/constants';
 import { IconVisibility, IconVisibilityOff } from '../Icon/internal';
 import { Primitive, ShowPasswordButtonProps } from '../types';
 
-const ariaLabelText = ComponentText.PasswordField;
+const { passwordIsHidden, passwordIsShown, showPassword } =
+  ComponentText.PasswordField;
 
 const ShowPasswordButtonPrimitive: Primitive<
   ShowPasswordButtonProps,
   typeof Button
 > = (
   {
     fieldType,
+    passwordIsHiddenLabel = passwordIsHidden,
+    passwordIsShownLabel = passwordIsShown,
+    showPasswordButtonLabel = showPassword,
     size,
-    hidePasswordButtonLabel,
-    showPasswordButtonLabel,
     ...rest
   },
   ref
 ) => {
   return (
     <Button
-      ariaLabel={
-        fieldType === 'password'
-          ? showPasswordButtonLabel || ariaLabelText.showPasswordButtonLabel
-          : hidePasswordButtonLabel || ariaLabelText.hidePasswordButtonLabel
-      }
+      aria-checked={fieldType !== 'password'}
+      ariaLabel={showPasswordButtonLabel}
       className={ComponentClassNames.FieldShowPassword}
       ref={ref}
+      role="switch"
       size={size}
       {...rest}
     >
+      <VisuallyHidden aria-live="polite">
+        {fieldType === 'password'
+          ? passwordIsHiddenLabel
+          : passwordIsShownLabel}
+      </VisuallyHidden>
       {fieldType === 'password' ? (
         <IconVisibility size={size} />
       ) : (

packages/react/src/primitives/PasswordField/__tests__/PasswordField.test.tsx

@@ -1,12 +1,9 @@
 import * as React from 'react';
 import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
 
 import { PasswordField } from '../PasswordField';
 import { ComponentClassNames, ComponentText } from '../../shared/constants';
 
-const ariaLabelText = ComponentText.PasswordField;
-
 describe('PasswordField component', () => {
   const testId = 'PasswordFieldTestId';
   it('should render classname for PasswordField', async () => {
@@ -39,8 +36,8 @@ describe('PasswordField component', () => {
     );
 
     await screen.findByTestId(testId);
-    expect(ref.current.nodeName).toBe('INPUT');
-    expect(showPasswordButtonRef.current.nodeName).toBe('BUTTON');
+    expect(ref.current?.nodeName).toBe('INPUT');
+    expect(showPasswordButtonRef.current?.nodeName).toBe('BUTTON');
   });
 
   it('should be password input type', async () => {
@@ -82,10 +79,10 @@ describe('PasswordField component', () => {
       />
     );
 
-    const button = await screen.findByRole('button');
+    const button = await screen.findByRole('switch');
     expect(button).toBeDefined();
     expect(button.getAttribute('aria-label')).toBe(
-      ariaLabelText.showPasswordButtonLabel
+      ComponentText.PasswordField.showPassword
     );
   });
 
@@ -102,60 +99,4 @@ describe('PasswordField component', () => {
     const button = screen.queryByRole('button');
     expect(button).toBeNull();
   });
-
-  describe(' - ShowPasswordButton', () => {
-    it('should toggle button type and label when clicked', async () => {
-      render(
-        <PasswordField
-          label="Password"
-          descriptiveText="Required"
-          name="password"
-          placeholder="Password"
-        />
-      );
-
-      const button = await screen.findByRole('button');
-      const passwordField = await screen.findByPlaceholderText('Password');
-
-      expect(passwordField.getAttribute('type')).toBe('password');
-      expect(button.getAttribute('aria-label')).toBe(
-        ariaLabelText.showPasswordButtonLabel
-      );
-
-      userEvent.click(button);
-
-      expect(passwordField.getAttribute('type')).toBe('text');
-      expect(button.getAttribute('aria-label')).toBe(
-        ariaLabelText.hidePasswordButtonLabel
-      );
-
-      userEvent.click(button);
-
-      expect(passwordField.getAttribute('type')).toBe('password');
-      expect(button.getAttribute('aria-label')).toBe(
-        ariaLabelText.showPasswordButtonLabel
-      );
-    });
-  });
-
-  it('should be able to customize show/hide password button label', async () => {
-    const showPasswordButtonLabel = 'Show my password';
-    const hidePasswordButtonLabel = 'Hide my password';
-    render(
-      <PasswordField
-        label="Password"
-        name="password"
-        placeholder="Password"
-        showPasswordButtonLabel={showPasswordButtonLabel}
-        hidePasswordButtonLabel={hidePasswordButtonLabel}
-      />
-    );
-
-    const button = await screen.findByRole('button');
-    expect(button).toHaveAttribute('aria-label', showPasswordButtonLabel);
-
-    userEvent.click(button);
-
-    expect(button).toHaveAttribute('aria-label', hidePasswordButtonLabel);
-  });
 });

packages/react/src/primitives/PasswordField/__tests__/ShowPasswordButton.test.tsx

@@ -1,18 +1,18 @@
 import * as React from 'react';
 import { render, screen } from '@testing-library/react';
 
+import { PasswordField } from '../PasswordField';
 import { ShowPasswordButton } from '../ShowPasswordButton';
 import { ComponentClassNames, ComponentText } from '../../shared/constants';
+import userEvent from '@testing-library/user-event';
 
-const ariaLabelText = ComponentText.PasswordField;
+const { passwordIsHidden, passwordIsShown } = ComponentText.PasswordField;
 
 describe('ShowPasswordButton component', () => {
-  const testId = 'testId';
-
   it('should render default classname for ShowPasswordButton', async () => {
     render(<ShowPasswordButton fieldType="password" />);
 
-    const button = await screen.findByRole('button');
+    const button = await screen.findByRole('switch');
 
     expect(button).toHaveClass(ComponentClassNames.FieldShowPassword);
   });
@@ -21,33 +21,79 @@ describe('ShowPasswordButton component', () => {
     const ref = React.createRef<HTMLButtonElement>();
     render(<ShowPasswordButton fieldType="password" ref={ref} />);
 
-    await screen.findByRole('button');
+    await screen.findByRole('switch');
 
-    expect(ref.current.nodeName).toBe('BUTTON');
+    expect(ref.current?.nodeName).toBe('BUTTON');
   });
 
-  it('should set correct ariaLabel for fieldType password', async () => {
-    const ref = React.createRef<HTMLButtonElement>();
-    render(<ShowPasswordButton fieldType="password" ref={ref} />);
+  it('should toggle field type, screen reader context, and aria-checked when clicked', async () => {
+    render(
+      <PasswordField
+        label="Password"
+        descriptiveText="Required"
+        name="password"
+        placeholder="Password"
+      />
+    );
 
-    await screen.findByLabelText(ariaLabelText.showPasswordButtonLabel);
+    const passwordField = await screen.findByPlaceholderText('Password');
+    const button = await screen.findByRole('switch');
+    const visuallyHidden = await screen.findByText(passwordIsHidden);
 
-    expect(ref.current.nodeName).toBe('BUTTON');
+    expect(passwordField.getAttribute('type')).toBe('password');
+    expect(button.getAttribute('aria-checked')).toBe('false');
+    expect(visuallyHidden.textContent).toBe(passwordIsHidden);
+
+    userEvent.click(button);
+
+    expect(passwordField.getAttribute('type')).toBe('text');
+    expect(button.getAttribute('aria-checked')).toBe('true');
+    expect(visuallyHidden.textContent).toBe(passwordIsShown);
+
+    userEvent.click(button);
+
+    expect(passwordField.getAttribute('type')).toBe('password');
+    expect(button.getAttribute('aria-checked')).toBe('false');
+    expect(visuallyHidden.textContent).toBe(passwordIsHidden);
   });
 
-  it('should set correct ariaLabel for fieldType text', async () => {
-    const ref = React.createRef<HTMLButtonElement>();
+  it('should be able to customize show password button label', async () => {
+    const showPasswordButtonLabel = 'Show my password';
+
+    render(
+      <PasswordField
+        label="Password"
+        name="password"
+        placeholder="Password"
+        showPasswordButtonLabel={showPasswordButtonLabel}
+      />
+    );
+
+    const button = await screen.findByRole('switch');
+    expect(button).toHaveAttribute('aria-label', showPasswordButtonLabel);
+  });
+
+  it('should be able to customize passwordIsHiddenLabel and passwordIsShownLabel', async () => {
+    const passwordIsHiddenLabel = 'Your password is hidden';
+    const passwordIsShownLabel = 'Your password is visible';
+
     render(
-      <ShowPasswordButton
-        fieldType="text"
-        className="custom-class"
-        ref={ref}
-        testId={testId}
+      <PasswordField
+        label="Password"
+        name="password"
+        placeholder="Password"
+        passwordIsHiddenLabel={passwordIsHiddenLabel}
+        passwordIsShownLabel={passwordIsShownLabel}
       />
     );
 
-    await screen.findByLabelText(ariaLabelText.hidePasswordButtonLabel);
+    const button = await screen.findByRole('switch');
+    const visuallyHidden = await screen.findByText(passwordIsHiddenLabel);
+
+    expect(visuallyHidden.textContent).toBe(passwordIsHiddenLabel);
+
+    userEvent.click(button);
 
-    expect(ref.current.nodeName).toBe('BUTTON');
+    expect(visuallyHidden.textContent).toBe(passwordIsShownLabel);
   });
 });