Author: Karen Stanley

1. Introduction

This document specifies all the behaviors of the Password Box component necessary for the control to be complete and delightful to use. This document is not meant to define the APIs or architecture. The goal of the specification is to ensure that we can deliver and validate UI components that are consistent, usable, appealing and sufficiently customizable to succeed in today's market. 

The Password Box is a field that allows users to specify a password. It is often used to allow users to create accounts, log in (or "sign in") to a web page or application, and is used in the process of changing a password. Passwords are used for security purposes. Only users who provide the correct password may gain access to a given user's information on the site or in the application. This is critically important for sites and applications that provide access to confidential information such as financial, medical, or human resources information.

2. Password Box Overview

When in use, the Password Box replaces entered text with a mask character for security reasons. An example Password box is shown below in the enabled state, (using the Caspian visual style). The example below shows the Password Box with a label, which is typical on the desktop platform.



Figure 1: Enabled Password Box control (Caspian visual style)


There are three main use cases for this control. Each of these use cases is identified below with a description of the most common interactions performed within each use case.
Note that in the use cases described below, when users enter their password, possible options for input include typing, pasting, or selecting characters, depending on the platform on which they are working and the context/use case in which they are working. 


Log In:
Users will use the Password Box when providing the password associated with their account name or user ID when logging into a web page or application. Users typically enter their password and then submit it along with their account name/user ID for validation and to be used as part of account authentication and eventual access to information.they are authorized to see and potentially work with.


Create Account:
When creating an account, users typically need to provide a password that must be used when logging into the web page or application for which the account was created (see the above use case). Users enter the password into one Password Box and then into a second in order to confirm the password. Once all account information has been entered, it is usually submitted for validation and account creation.


Change Password:
At times, users may wish to change the password associated with an account. In order to do this users typically must first enter their existing password. Then they enter a new password and then re-enter their new password to confirm it. 

One may also know this control by the name: Password Field.

3. Password Box: Desktop

3.1 Desktop - Introduction

On the desktop users may enter passwords by typing them or pasting them into the Password box. 

Different sites/applications and use cases may have different requirements regarding the ability to paste a password into a Password Box field. For this reason, the Password Box control must be configurable so developers have the option to allow this capability or not.

3.2 Desktop - Visual Design

• All Password Box images on the Desktop platform should be considered placeholders shown using the Caspian Visual Design Style for JavaFX. 
• Actual visual design will be provided by our Visual Design team.

The following image shows the password box in its three possible states: Normal (Enabled), Focused, and Disabled. 

Figure 2: Enabled (Normal), Focused, Disabled Password Box controls (Caspian visual style)

For more visual design details see the Caspian Visual Design Style for JavaFX, sections 4:11 Text Box and 4:12 Password Box.

3.3 Desktop - Detailed Behaviors

Detailed behaviors associated with the Password Box in its three possible states are described below.

Enabled:

 
Figure 3: Enabled Password Box control (Caspian visual style)


When the password box is enabled, it displays a mask character for any characters that have been entered. If no characters have been entered, it is blank. The control is ready to receive focus.


Focused:

  
Figure 4: Focused Password Box control (Caspian visual style)


When the Password Box receives focus, by being tabbed to or clicked in, its border is shown highlighted. When tabbing into the control any existing text is selected, where when clicking into the control, the I-beam cursor is inserted into the existing text where clicked. If there is no existing input, the cursor is placed at the left side of the control. When the I-beam cursor is displayed it is positioned at the next input location. (The above image shows that the user has entered eight characters and the I-beam curser waits for the 9th.)


Behaviors when in Focused State:

For every character that is input, it is displayed in the Password Box control for the number of seconds indicated by the developer (specified in the Actual Character Display Time attribute) and then replaced with the mask character. This gives the user the chance to verify what they have entered before continuing.Note, however, that if another character is input before the actual character display time completes, the display of the actual entered character is abandoned and the character is replaced with the mask character at the time the next character is input.

Allowing users to see the actual entered character is not as important on the desktop as it is on other platforms such as Mobile and TV, but some developers may elect to allow the characters to be seen briefly.

When users are done entering a password, they typically indicate this by pressing the Enter key while focus is in the control. (Other ways the user may do this are by tabbing out of the control or clicking on another control.) When this happens, the Password Box control returns the entered password and all application control to the calling application which would then be responsible for determining what action to take next. The Password Box would remain in focused state until the calling application moves the focus. The mask characters would remain displayed in the control by default. Possible actions that the controlling application may take at this point include:
    - move focus to the next control, waiting to validate until the entire page is submitted for validation.
    - validate password immediately, display an error message and re-call Password Box so the password may be corrected
    - validate password immediately  and place focus on the next appropriate UI control
    - validate password immediately and invoke the default Button 


Other behaviors:

• Cut to the clipboard and copy are disabled for the Password Box so users cannot cut or copy information from the Password Box control to the clipboard. This is for security reasons.
• Some situations may allow users to Paste input into the Password Box control. However some developers may choose to disable the ability to Paste into the control (both have been seen in use.) For this reason, the control must support the ability to disallow pasting into it, whether it is decided to support this through an API (a developer option) or by suggesting developers use some other coding mechanism such as using a sub-class. 
• CAPS LOCK feature is not for 1.3: When the user presses the CAPS LOCK keyboard key, a key symbol is optionally displayed within the Password Box control (or only if not possible, to the right of the Password Box control). This is to show that the characters being input are all caps (since the user may not have the opportunity to see the characters being entered. (This feature may be turned off.)
  
  Note: the lock indicators shown in the examples below are placeholders. Visual design is still TBD.
  
     Icon Tool Tip: CAPS LOCK is on
  Figure 5: Focused Password Box control with CAPS LOCK key indicator inside control (Caspian visual style / Icon not final!)
  
  
  (Place the icon outside of the control only if placing it inside the password box control cannot be done.
  Note that if done this way AND password strength is also being displayed, password strength would be shown to the right of the CAPS LOCK icon )
  Icon Tool Tip: CAPS LOCK is on
  Figure 6: Focused Password Box control with CAPS LOCK key indicator to the right of the control (Caspian visual style / Icon not final!)
  
  
  When focus leaves the field or CAPS LOCK is disengaged, the caps lock indicator disappears. 
  If the CAPS LOCK is engaged when the field first receives input focus, the visual indicator is displayed.

Get the CapsLock and NumLock icons from here.

• Minimum Password Length feature is not for 1.3: If the Password Box control is called with a value specified indicating the minimum required number of characters needed for a valid password, a placeholder character (e.g. an underscore character or some other character, perhaps specified by the developer - decision on this is still outstanding) is shown for each character needed to meet the minimum requirement. Each time the user enters a character, the placeholder character is replaced by either the actual character followed by the the mask character or just by the mask character (as described above) 
  
  Note: the visual treatment shown below is a placeholder. Visual design is still TBD.
  
  
  Figure 7: Focused Password Box control showing placeholder characters to indicate minimum password length (Caspian visual style)
  
  
• Maximum Password Length feature is not for 1.3: If the Password Box control is called with a value specified indicating the maximum number of characters allowed for a valid password, the Password Box control stops accepting input when that value is reached. Additionally the developer can optionally elect to have a sound (beep) produced when the user tries to enter more than the maximum number of allowed characters. The default would be not to sound the beep.
• Password Strength feature is not for 1.3: In some use cases (such as when a user is creating a password for an account or when changing a password), developers may choose to have a password strength indicator displayed along with the Password Box control. This strength indicator would be updated as each character is input using a call-back function from the Password Box control to the calling application. This feature is optional, but if used the indicator would display as shown below. 
  
  Note: the visual treatments shown below are placeholders. Visual design is still TBD.
  
  
  
  
  
  
  Figure 8: Focused Password Box controls with password strength indicators (Caspian visual style - password strength indicators not final!)

• Password Clear feature is not for 1.3: There should be a way for developers to clear what is displayed in the Password Box control. This allows developers who do not want to show that a password has been entered to clear any mask (or non-mask) characters that may be displayed. (This feature may possibly be combined as part of the Password Pad feature, depending on how robust that feature becomes. Perhaps it may become an overall "Password Display" feature.)
• Password Pad feature is not for 1.3: There should be a way for developers to indicate that they want the whole width of the Password Box to be filled with the mask character after the user has entered a password - or otherwise indicate what the displayed password should look like, details yet to be determined. This gives developers control over how entered passwords are displayed after they've been entered. (This feature may possibly include the Password Clear feature, depending on how robust this feature turns out to be upon further consideration. Perhaps it may become an overall "Password Display" feature.)
  
  
  Disabled:
  
  
  Figure 4: Disabled Password Box control (Caspian visual style)
  
  Although it may be unusual for this control to appear in a disabled state, it is plausible that a site or application may want to disable the Password Box control. One example may be that the control is disabled until an account name or user ID is entered. 
  
  In the disabled state, the Password Box is "grayed out" (details are governed by the visual design specification being used) to indicate that is cannot receive input. Any input already entered is displayed using a "grayed out" mask character. (The number of mask characters to display - or just what to display - may be developer-controlled post-SoMa.) The control does not accept focus when tabbed to or clicked on. 
  
  
  
  States:
  The following table identifies the applicable states pertaining to the Password Box control.

State Name	Description	Visual Appearance
Enabled	Control is displayed. Any existing input is replaced with a mask character.(The number of mask characters to display - or just what to display - may be developer-controlled post-1.3.)	Figure 9: Enabled Password Box control (Caspian visual style)
Focused	Control is ready for input. A mask character is displayed for each character that is input by the user. (The actual character may be displayed briefly before mask character is displayed.)	I-beam cursor blinks at input location.  Figure 10: Focused Password Box control (Caspian visual style)
Disabled	Control cannot accept input or be navigated to.	Figure 11: Disabled Password Box control (Caspian visual style)

3.4 Desktop - Keyboard Support

3.4.1 Windows Keyboard Support

3.4.2 MAC Keyboard Support

Keyboard behaviors are the same as for Windows keyboard support.

3.4.3 Linux Keyboard Support

Keyboard behaviors are the same as for Windows keyboard support.

3.5 Desktop - Attributes

Below is a table indemnifying the attributes required by the Password Box control.

Note that the Password Box will inherit attributes of the Text Box control including:

• text box width
• text box height
• vertical position with respect to parent
• horizontal position with respect to parent
• font details (e.g. font, size, style, color - as available for the text field control)
• shadow text (which displays initial "prompt" (or hint) information in the field)

Particular to Password Box will be the following:   

4. Password Box: Touch

4.1 Touch - Introduction

The Mobile Touch platform introduces some additional considerations not seen on the desktop:

• Interaction is conducted on a mobile device which will be much smaller than any desktop.
• Mobile Touch allows for direct manipulation (finger touch/gestures) of content and objects, which may be considered more natural than using an input device such as a keyboard or mouse or hardware keypad.
• Some mobile devices may allow the use of a stylus as well as finger touch, while others may not. A stylus introduces different gesture considerations.
• Text input involves an on-screen keyboard that typically toggles between displaying alphanumeric characters and a number pad.

4.2 Touch - Visual Design

* All Password Box images on the Touch platform should be considered placeholders. Actual visual design will be provided by our Visual Design team.

The following image shows the Password Box in its three possible states: Normal (Enabled), Focused, and Disabled.
(They are based on the Text Field control that runs on the desktop platform (it is the same code running). Of course, the dimensions are adjusted to accommodate the mobile device.)


Figure 12: Enabled (Normal), Focused, and Disabled Password Box controls (Caspian visual style - check with visual designers to see if adjustments are needed for Touch)

4.3 Touch - Detailed Behaviors

Below is a description of the behaviors and interactions pertaining to the Password Box on the Touch platform.

Note that this specification assumes the invocation and use of an on-screen keyboard for text input.

The potential use cases applicable to the Touch platform are similar to the use cases for Desktop:

• Create Password (to protect access to an application or web site)
• Log In (Examples: (provide the password to log into an application or web site)
• Change password (change the password for access to an application or web site)

Applicable states are also similar to the Desktop: Enabled, Focused and Disabled.

Detailed behaviors associated with the Password Box in its three possible states are described below.


Enabled:

 
 Figure 13: Enabled Password Box control (Caspian visual style - check with visual designers to see if adjustments are needed for Touch)

When the password box is enabled, it displays a mask character for any characters that have been entered. (The number of mask characters to display - or just what to display - may be developer-controlled post-1.3.) If no characters have been entered, it is blank. The control is ready to receive focus.



Focused:

  
 Figure 14: Focused Password Box control (Caspian visual style - check with visual designers to see if adjustments are needed for Touch)

When the Password Box receives focus, by being tapped (with finger or stylus), it is shown highlighted. The I-beam cursor blinks at the next input location. When the field receives focus, a keyboard also typically appears. (The above image shows that the user has entered eight characters and the I-beam curser waits for the 9th.)


Behaviors when in Focused State: 

As users tap the keys on the keyboard there is visual feedback on the characters (varies by platform) and there is also input into the Password Box control. Selected characters are displayed in the Password Box control for the number of seconds indicated by the developer (specified in the Actual Character Display Time attribute) and then replaced with the mask character. This gives the user the chance to verify what they have entered before continuing. Note, however, that if another character is input before the actual character display time completes, the display of the actual entered character is abandoned and the character is replaced with the mask character at the time the next character is input.

Displaying the actual character is especially important on Touch platforms that don't use a standard QWERTY keyboard where it is less predictable that the user has entered the character they expected. 

To correct an incorrect selection, the user chooses the keyboard key that allows deletion of the input to the left of the I-beam cursor, typically the backspace key.

Here is an example using a keyboard with multiple characters available per touch button:

* All Password Box images on the Touch platform should be considered placeholders. Actual visual design will be provided by our Visual Design team.


Figure 15: Example of Password Box control with on-screen keyboard (Caspian visual style for control - check with visual designers to see if adjustments are needed for Touch)

Other examples layouts of mobile touch keyboards are shown below:

Figure 16: Example showing three possible on-screen keyboard layouts 

When the user has finished entering the password, the Enter (or whatever button the keyboard provides to indicate "finished") button can be tapped. This dismisses the keyboard. (Another means to dismiss the keyboard would be to click an icon on the bottom bar or on another component in an (native) application, which doesn't allow text input.) At this point, the Password Box control returns the entered password and all application control to the calling application which would then be responsible for determining what action to take next. The Password Box would remain in focused state until the calling application moves the focus. The mask characters would remain displayed in the control by default. (Note that the number of mask characters to display - or just what to display - may be developer-controlled post-1.3.) Possible actions that the controlling application may take at this point include:
    - move focus to the next control, waiting to validate until the entire page is submitted for validation.
    - validate password immediately, display an error message and re-call Password Box so the password may be corrected
    - validate password immediately  and place focus on the next appropriate UI control
    - validate password immediately and invoke the default Button on the page.

Other behaviors:

• Cut to the clipboard and copy are disabled for the Password Box so users cannot cut or copy information from the Password Box control to the clipboard. This is for security reasons.
• Paste is not for 1.3 on Touch: Because the clipboard is not supported on touch devices in 1.3 release, Paste cannot be supported. 
  (For Future: In some situations users may be allowed to Paste input into the Password Box control. However some developers may choose to disable the ability to Paste into the control (both have been seen in use.) For this reason, when Paste is supported, the control must must support the ability to disallow pasting into it, whether it is decided to support this through an API (option) or by suggesting developers use some other coding mechanism such as using a sub-class.)
• Not for Touch: CAPS LOCK indication within the Password Box control (as described for the desktop platform) is not applicable on touch devices for the following reasons:
  • CAPS LOCK is not typically available in on-screen keyboards on touch devices
  • Even if CAPS LOCK is available, there would not currently be a way for the control to know if CAPS LOCK had been engaged on the on-screen keyboard.
  • Because the on-screen keyboard CAPS LOCK key itself should indicate that CAPS LOCK is on, and since this indicator is within the user's current area of focus, there is no need for a separate symbol (as defined for Desktop) to indicate this.
  • Not including this feature simplifies the user interface appropriately for the small area available on mobile devices while still providing current state information to the user.
• Minimum Password Length feature is not for 1.3: If the Password Box control is called with a value specified indicating the minimum required number of characters needed for a valid password, a placeholder character (e.g. an underscore character or some other character, perhaps specified by the developer - decision on this is still outstanding) is shown for each character needed to meet the minimum requirement. Each time the user enters a character, the placeholder character is replaced by either the actual character followed by the the mask character or just by the mask character (as described above) 
  
  Note: the visual treatment shown below is a placeholder. Visual design is still TBD.
  
  
  Figure 17: Focused Password Box control showing placeholder characters to indicate minimum password length (Caspian visual style -check with visual designers to see if adjustments are needed for Touch)
  
  
• Maximum Password Length feature is not for 1.3: If the Password Box control is called with a value specified indicating the maximum number of characters allowed for a valid password, the Password Box control stops accepting input when that value is reached. Additionally the developer can optionally elect to have a sound (beep) produced when the user tries to enter more than the maximum number of allowed characters. The default would be not to sound the beep.
• Password Strength feature is not for 1.3: In some use cases (such as when a user is creating a password for an account or when changing a password), developers may choose to have a password strength indicator displayed along with the Password Box control. This strength indicator would be updated as each character is input using a call-back function from the Password Box control to the calling application. This feature is optional, but if used the indicator would display as shown below. Note that for mobile devices, the password strength is indicated using an icon instead of a graphic display with text as on desktop.
  :
  Note: the visual treatments shown below are placeholders. Visual design is still TBD.
  
  Icon Tool tip: Password Strength: Too Short
  Icon Tool tip: Password Strength: Fair
  Icon Tool tip: Password Strength: Good
  Icon Tool tip: Password Strength: Strong
  Figure 18: Focused Password Box controls with icons as password strength indicators (Caspian visual style - check with visual designers to see if adjustments are needed for Touch / Icons not final!)
  
  
• Password Clear feature is not for 1.3: There should be a way for developers to clear what is displayed in the Password Box control. This allows developers who do not want to show that a password has been entered to clear any mask (or non-mask) characters that may be displayed. (This feature may possibly be combined as part of the Password Pad feature, depending on how robust that feature becomes. Perhaps it may become an overall "Password Display" feature.)
• Password Pad feature is not for 1.3: There should be a way for developers to indicate that they want the whole width of the Password Box to be filled with the mask character after the user has entered a password - or otherwise indicate what the displayed password should look like, details yet to be determined. This gives developers control over how entered passwords are displayed after they've been entered. (This feature may possibly include the Password Clear feature, depending on how robust this feature turns out to be upon further consideration. Perhaps it may become an overall "Password Display" feature.)
  
  

Disabled:

 
 Figure 19: Disabled Password Box control (Caspian visual style - check with visual designers to see if adjustments are needed for Touch)

Although it may be unusual for this control to appear in a disabled state, it is plausible that a site or application may want to disable the Password Box control. One example may be that the control is disabled until an account name or user ID is entered. 

In the disabled state, the Password Box is "grayed out" (details are governed by the visual design specification being used) to indicate that is cannot receive input. Any input already entered is displayed using a "grayed out" mask character. (The number of mask characters to display - or just what to display - may be developer-controlled post-1.3.) The control does not accept focus when tapped and cannot otherwise be navigated to.



States:
The following table identifies the applicable states pertaining to the Password Box control.

State Name	Description	Visual Appearance
Enabled	Control is displayed. Any existing input is replaced with a mask character.(The number of mask characters to display - or just what to display - may be developer-controlled post-SoMa.)	Figure 20: Enabled Password Box control (Caspian visual style -check with visual designers to see if adjustments are needed for Touch)
Focused	Control is ready for input. A mask character is displayed for each character that is input by the user. (The actual character may be displayed briefly before mask character is displayed.)	I-beam cursor blinks at input location.  Figure 21: Focused Password Box control (Caspian visual style -check with visual designers to see if adjustments are needed for Touch)
Disabled	Control cannot accept input or be navigated to.	Figure 22: Disabled Password Box control (Caspian visual style -check with visual designers to see if adjustments are needed for Touch)

4.4 Touch - On-Screen Keyboard Support

This section describes keys & key behavior when using an on-screen keyboard. The keys identified here are considered to be common across keyboards, though keyboard keys and layout tend to vary.

On-Screen Keyboard Notes: 
  - Tapping a key once selects the left-most primary (large) item displayed on a key with multiple items.
  - Tapping two times in quick succession selects the item to the right of the left-most item; three times moves to the right of that.
  - Tapping Shift and then another key selects the secondary (smaller - and usually a top) item on the key.
  - Tapping the '123' item toggles the on-screen keyboard to a numeric keyboard.

4.5 Touch - Attributes

Below is a table indemnifying the attributes required by the Password Box control on the Touch platform.

Note that the Password Box will inherit attributes of the Text Box control including:

• text box width
• text box height
• vertical position with respect to parent
• horizontal position with respect to parent
• font details (e.g. font, size, style, color - as available for the text field control)
• shadow text (which displays initial "prompt" (or hint) information in the field)

Particular to Password Box will be the following: