feat(input): add input-password-toggle component (#29175)

Issue number: Internal

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

When given a password input it is hard to know what users are typing as
the contents of the input are obscured. As a result, it is a common
pattern to have a button that lets users temporarily toggle the
visibility of the password so they can correct any mistakes. Ionic
currently has the infrastructure for developers to implement this on
their own, but this use case is so common that the team thinks it is
worth having this functionality built-in to Ionic.

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Introduces the `ion-input-password-toggle` component. This component
is a button that toggles the visibility of the text in the input it is
slotted into.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->


⚠️ Give co-author credit to
#29141 on merge.

Docs PR: ionic-team/ionic-docs#3541

Note: We did not do the approach listed in the other PR due to
#29141 (comment).

---------

Co-authored-by: OS-giulianasilva <[email protected]>

Author: liamdebeasi

core/api.txt

@@ -558,7 +558,7 @@ ion-input,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secon
 ion-input,prop,counter,boolean,false,false,false
 ion-input,prop,counterFormatter,((inputLength: number, maxLength: number) => string) | undefined,undefined,false,false
 ion-input,prop,debounce,number | undefined,undefined,false,false
-ion-input,prop,disabled,boolean,false,false,false
+ion-input,prop,disabled,boolean,false,false,true
 ion-input,prop,enterkeyhint,"done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined,undefined,false,false
 ion-input,prop,errorText,string | undefined,undefined,false,false
 ion-input,prop,fill,"outline" | "solid" | undefined,undefined,false,false
@@ -575,7 +575,7 @@ ion-input,prop,multiple,boolean | undefined,undefined,false,false
 ion-input,prop,name,string,this.inputId,false,false
 ion-input,prop,pattern,string | undefined,undefined,false,false
 ion-input,prop,placeholder,string | undefined,undefined,false,false
-ion-input,prop,readonly,boolean,false,false,false
+ion-input,prop,readonly,boolean,false,false,true
 ion-input,prop,required,boolean,false,false,false
 ion-input,prop,shape,"round" | undefined,undefined,false,false
 ion-input,prop,spellcheck,boolean,false,false,false
@@ -607,6 +607,12 @@ ion-input,css-prop,--placeholder-font-style
 ion-input,css-prop,--placeholder-font-weight
 ion-input,css-prop,--placeholder-opacity
 
+ion-input-password-toggle,shadow
+ion-input-password-toggle,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
+ion-input-password-toggle,prop,hideIcon,string | undefined,undefined,false,false
+ion-input-password-toggle,prop,mode,"ios" | "md",undefined,false,false
+ion-input-password-toggle,prop,showIcon,string | undefined,undefined,false,false
+
 ion-item,shadow
 ion-item,prop,button,boolean,false,false,false
 ion-item,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true

core/src/components.d.ts

@@ -1287,6 +1287,25 @@ export namespace Components {
          */
         "value"?: string | number | null;
     }
+    interface IonInputPasswordToggle {
+        /**
+          * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
+         */
+        "color"?: Color;
+        /**
+          * The icon that can be used to represent hiding a password. If not set, the "eyeOff" Ionicon will be used.
+         */
+        "hideIcon"?: string;
+        /**
+          * The mode determines which platform styles to use.
+         */
+        "mode"?: "ios" | "md";
+        /**
+          * The icon that can be used to represent showing a password. If not set, the "eye" Ionicon will be used.
+         */
+        "showIcon"?: string;
+        "type": TextFieldTypes;
+    }
     interface IonItem {
         /**
           * If `true`, a button tag will be rendered and the item will be tappable.
@@ -3811,6 +3830,12 @@ declare global {
         prototype: HTMLIonInputElement;
         new (): HTMLIonInputElement;
     };
+    interface HTMLIonInputPasswordToggleElement extends Components.IonInputPasswordToggle, HTMLStencilElement {
+    }
+    var HTMLIonInputPasswordToggleElement: {
+        prototype: HTMLIonInputPasswordToggleElement;
+        new (): HTMLIonInputPasswordToggleElement;
+    };
     interface HTMLIonItemElement extends Components.IonItem, HTMLStencilElement {
     }
     var HTMLIonItemElement: {
@@ -4635,6 +4660,7 @@ declare global {
         "ion-infinite-scroll": HTMLIonInfiniteScrollElement;
         "ion-infinite-scroll-content": HTMLIonInfiniteScrollContentElement;
         "ion-input": HTMLIonInputElement;
+        "ion-input-password-toggle": HTMLIonInputPasswordToggleElement;
         "ion-item": HTMLIonItemElement;
         "ion-item-divider": HTMLIonItemDividerElement;
         "ion-item-group": HTMLIonItemGroupElement;
@@ -5993,6 +6019,25 @@ declare namespace LocalJSX {
          */
         "value"?: string | number | null;
     }
+    interface IonInputPasswordToggle {
+        /**
+          * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
+         */
+        "color"?: Color;
+        /**
+          * The icon that can be used to represent hiding a password. If not set, the "eyeOff" Ionicon will be used.
+         */
+        "hideIcon"?: string;
+        /**
+          * The mode determines which platform styles to use.
+         */
+        "mode"?: "ios" | "md";
+        /**
+          * The icon that can be used to represent showing a password. If not set, the "eye" Ionicon will be used.
+         */
+        "showIcon"?: string;
+        "type"?: TextFieldTypes;
+    }
     interface IonItem {
         /**
           * If `true`, a button tag will be rendered and the item will be tappable.
@@ -8040,6 +8085,7 @@ declare namespace LocalJSX {
         "ion-infinite-scroll": IonInfiniteScroll;
         "ion-infinite-scroll-content": IonInfiniteScrollContent;
         "ion-input": IonInput;
+        "ion-input-password-toggle": IonInputPasswordToggle;
         "ion-item": IonItem;
         "ion-item-divider": IonItemDivider;
         "ion-item-group": IonItemGroup;
@@ -8138,6 +8184,7 @@ declare module "@stencil/core" {
             "ion-infinite-scroll": LocalJSX.IonInfiniteScroll & JSXBase.HTMLAttributes<HTMLIonInfiniteScrollElement>;
             "ion-infinite-scroll-content": LocalJSX.IonInfiniteScrollContent & JSXBase.HTMLAttributes<HTMLIonInfiniteScrollContentElement>;
             "ion-input": LocalJSX.IonInput & JSXBase.HTMLAttributes<HTMLIonInputElement>;
+            "ion-input-password-toggle": LocalJSX.IonInputPasswordToggle & JSXBase.HTMLAttributes<HTMLIonInputPasswordToggleElement>;
             "ion-item": LocalJSX.IonItem & JSXBase.HTMLAttributes<HTMLIonItemElement>;
             "ion-item-divider": LocalJSX.IonItemDivider & JSXBase.HTMLAttributes<HTMLIonItemDividerElement>;
             "ion-item-group": LocalJSX.IonItemGroup & JSXBase.HTMLAttributes<HTMLIonItemGroupElement>;

core/src/components/alert/test/a11y/alert.e2e.ts-snapshots/alert-scale-ios-ltr-Mobile-Chrome-linux.png

@@ -0,0 +1,152 @@
+import type { ComponentInterface } from '@stencil/core';
+import { Component, Element, Host, Prop, h, Watch } from '@stencil/core';
+import { printIonWarning } from '@utils/logging';
+import { createColorClasses } from '@utils/theme';
+import { eyeOff, eye } from 'ionicons/icons';
+
+import { getIonMode } from '../../global/ionic-global';
+import type { Color, TextFieldTypes } from '../../interface';
+
+/**
+ * @virtualProp {"ios" | "md"} mode - The mode determines which platform styles to use.
+ */
+@Component({
+  tag: 'ion-input-password-toggle',
+  /**
+   * Empty CSS files are required in order for the mode to be inherited to the
+   * inner ion-button. Otherwise, the setMode callback provided to Stencil will not get called
+   * and we will default to MD mode.
+   */
+  styleUrls: {
+    ios: 'input-password-toggle.scss',
+    md: 'input-password-toggle.scss',
+  },
+  shadow: true,
+})
+export class InputPasswordToggle implements ComponentInterface {
+  private inputElRef!: HTMLIonInputElement | null;
+
+  @Element() el!: HTMLIonInputElement;
+
+  /**
+   * The color to use from your application's color palette.
+   * Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
+   * For more information on colors, see [theming](/docs/theming/basics).
+   */
+  @Prop({ reflect: true }) color?: Color;
+
+  /**
+   * The icon that can be used to represent showing a password. If not set, the "eye" Ionicon will be used.
+   */
+  @Prop() showIcon?: string;
+
+  /**
+   * The icon that can be used to represent hiding a password. If not set, the "eyeOff" Ionicon will be used.
+   */
+  @Prop() hideIcon?: string;
+
+  /**
+   * @internal
+   */
+  @Prop({ mutable: true }) type: TextFieldTypes = 'password';
+
+  /**
+   * Whenever the input type changes we need to re-run validation to ensure the password
+   * toggle is being used with the correct input type. If the application changes the type
+   * outside of this component we also need to re-render so the correct icon is shown.
+   */
+  @Watch('type')
+  onTypeChange(newValue: TextFieldTypes) {
+    if (newValue !== 'text' && newValue !== 'password') {
+      printIonWarning(
+        `ion-input-password-toggle only supports inputs of type "text" or "password". Input of type "${newValue}" is not compatible.`,
+        this.el
+      );
+
+      return;
+    }
+  }
+
+  connectedCallback() {
+    const { el } = this;
+
+    const inputElRef = (this.inputElRef = el.closest('ion-input'));
+
+    if (!inputElRef) {
+      printIonWarning(
+        'No ancestor ion-input found for ion-input-password-toggle. This component must be slotted inside of an ion-input.',
+        el
+      );
+
+      return;
+    }
+
+    /**
+     * Important: Set the type in connectedCallback because the default value
+     * of this.type may not always be accurate. Usually inputs have the "password" type
+     * but it is possible to have the input to initially have the "text" type. In that scenario
+     * the wrong icon will show briefly before switching to the correct icon. Setting the
+     * type here allows us to avoid that flicker.
+     */
+    this.type = inputElRef.type;
+  }
+
+  disconnectedCallback() {
+    this.inputElRef = null;
+  }
+
+  private togglePasswordVisibility = () => {
+    const { inputElRef } = this;
+
+    if (!inputElRef) {
+      return;
+    }
+
+    inputElRef.type = inputElRef.type === 'text' ? 'password' : 'text';
+  };
+
+  render() {
+    const { color, type } = this;
+
+    const mode = getIonMode(this);
+
+    const showPasswordIcon = this.showIcon ?? eye;
+    const hidePasswordIcon = this.hideIcon ?? eyeOff;
+
+    const isPasswordVisible = type === 'text';
+
+    return (
+      <Host
+        class={createColorClasses(color, {
+          [mode]: true,
+        })}
+      >
+        <ion-button
+          mode={mode}
+          color={color}
+          fill="clear"
+          shape="round"
+          aria-checked={isPasswordVisible ? 'true' : 'false'}
+          aria-label="show password"
+          role="switch"
+          type="button"
+          onPointerDown={(ev) => {
+            /**
+             * This prevents mobile browsers from
+             * blurring the input when the password toggle
+             * button is activated.
+             */
+            ev.preventDefault();
+          }}
+          onClick={this.togglePasswordVisibility}
+        >
+          <ion-icon
+            slot="icon-only"
+            aria-hidden="true"
+            icon={isPasswordVisible ? hidePasswordIcon : showPasswordIcon}
+          ></ion-icon>
+        </ion-button>
+      </Host>
+    );
+  }
+}

core/src/components/input-password-toggle/input-password-toggle.scss

@@ -0,0 +1,23 @@
+import AxeBuilder from '@axe-core/playwright';
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ directions: ['ltr'] }).forEach(({ title, config }) => {
+  test.describe(title('input password toggle: a11y'), () => {
+    test('should not have accessibility violations', async ({ page }) => {
+      await page.setContent(
+        `
+          <main>
+            <ion-input label="input" type="password">
+              <ion-input-password-toggle slot="end"></ion-input-password-toggle>
+            </ion-input>
+          </main>
+        `,
+        config
+      );
+
+      const results = await new AxeBuilder({ page }).analyze();
+      expect(results.violations).toEqual([]);
+    });
+  });
+});

core/src/components/input-password-toggle/input-password-toggle.tsx

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Input - Toggle Password</title>
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <link href="../../../../../css/ionic.bundle.css" rel="stylesheet" />
+    <link href="../../../../../scripts/testing/styles.css" rel="stylesheet" />
+    <script src="../../../../../scripts/testing/scripts.js"></script>
+    <script nomodule src="../../../../../dist/ionic/ionic.js"></script>
+    <script type="module" src="../../../../../dist/ionic/ionic.esm.js"></script>
+    <style>
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(5, minmax(250px, 1fr));
+        grid-row-gap: 20px;
+        grid-column-gap: 20px;
+      }
+      h2 {
+        font-size: 12px;
+        font-weight: normal;
+
+        color: #6f7378;
+
+        margin-top: 10px;
+      }
+      @media screen and (max-width: 800px) {
+        .grid {
+          grid-template-columns: 1fr;
+          padding: 0;
+        }
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>Input - Basic</ion-title>
+        </ion-toolbar>
+      </ion-header>
+
+      <ion-content id="content" class="ion-padding">
+        <div class="grid">
+          <div class="grid-item">
+            <h2>Default</h2>
+            <ion-input type="password" value="supersecurepassword" label="Password">
+              <ion-input-password-toggle slot="end"></ion-input-password-toggle>
+            </ion-input>
+          </div>
+          <div class="grid-item">
+            <h2>Custom Icon</h2>
+            <ion-input type="password" value="supersecurepassword" label="Password">
+              <ion-input-password-toggle show-icon="trash" slot="end"></ion-input-password-toggle>
+            </ion-input>
+          </div>
+          <div class="grid-item">
+            <h2>Custom Mode/Color</h2>
+            <ion-input type="password" value="supersecurepassword" label="Password">
+              <ion-input-password-toggle
+                color="danger"
+                mode="ios"
+                show-icon="trash"
+                slot="end"
+              ></ion-input-password-toggle>
+            </ion-input>
+          </div>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>