@xsolla/xui-input-password 0.174.2 → 0.175.0

package/README.md

@@ -1,6 +1,82 @@
 # Input Password
 
 A cross-platform React password input component with visibility toggle, validation checkmark, and clear functionality.
+<!-- BEGIN:xui-mcp-instructions:input-password -->
+A specialised text input for password entry. Extends the standard input with password-specific controls: a show/hide visibility toggle, an optional clear button, an optional check icon for password confirmation fields, and a right icons block that groups these controls. Always renders with type=*"password"* semantics (masked by default) unless the user explicitly toggles visibility.
+
+### When to use
+
+For any field where the user must enter a password — login, registration, account settings, password reset
+
+For password confirmation fields (e.g. *"Confirm new password"*) — use alongside the primary password field
+
+When the form requires the user to create a new password and strength feedback is shown nearby
+
+### When not to use
+
+- For non-sensitive text fields — use the standard Input component
+- For PINs or short numeric codes — use a dedicated PIN input or a numeric Input with inputmode=*"numeric"*
+- When the input must always remain masked with no reveal option (e.g. a hardware security key PIN) — handle with a custom component that omits the visibility toggle
+
+### Content guidelines
+
+Placeholder text — use Password or a format hint like At least 8 characters for create-password fields. Do not use verbose instructions as placeholder — they disappear when the user starts typing.
+
+Field labels — always provide a visible label: *"Password"*, *"Current password"*, *"New password"*, *"Confirm new password"*. Do not rely on placeholder alone.
+Error messages — be specific:
+- *"Password is required"*
+- *"Password must be at least 8 characters"*
+- *"Password must contain at least one number and one special character"*
+- *"Passwords do not match"* (on the confirm field)
+- *"Incorrect password"* (on the login form after a failed attempt)
+- Visibility toggle label — the toggle icon button must have an accessible label that reflects the current state: aria-label=*"Show password"* when masked, aria-label=*"Hide password"* when revealed.
+- Avoid password rules in error messages only — communicate password requirements upfront (e.g. in a helper text or a requirements list below the field) so users know the rules before they make a mistake.
+
+Behaviour guidelines (from industry practice)
+
+Default masking — the field must always render in masked state (Visibility=False) on mount, even if a value is pre-filled. Never initialise with Visibility=True.
+
+Visibility toggle — clicking the eye icon toggles between masked and plain text. The toggle must work with mouse, touch, and keyboard (Enter/Space when the icon has focus). After toggling, focus must remain in the input field, not on the icon button.
+
+Remove button — show the remove button only when the field has a value (Filled=True). Hide it in the empty state. Clicking removes the value and returns focus to the input.
+
+Check icon right — update in real time as the user types in either password field. Show when values match, hide when they diverge. Do not show the check icon if either field is empty.
+
+Autocomplete — use autocomplete=*"current-password"* for login/current-password fields and autocomplete=*"new-password"* for create-password/confirm-password fields. This allows password managers to fill and save credentials correctly and satisfies WCAG 1.3.5.
+
+Password managers — do not block paste (onpaste prevention) in password fields. Password managers and users rely on paste. Blocking paste is a security anti-pattern and degrades usability significantly.
+
+Validation timing — validate on blur (when the user leaves the field) or on form submit. Do not validate every keystroke. For *"Confirm password"* fields, re-validate when either field changes.
+
+Error state — switch to State=Error with a specific error message on blur or submit:
+- If the password does not meet requirements, show which requirement failed
+- If passwords do not match, show the error on the confirm field (not the primary)
+- Strength indicator — password strength feedback (e.g. a progress bar or label) lives outside the InputPassword component. Place it between the primary and confirm password fields.
+- Caps Lock warning — optionally surface a Caps Lock indicator when the user has Caps Lock active in a masked field. Show it as a helper text below the field or a tooltip on the visibility icon.
+- Disabled state — use State=Disable for fields that cannot be edited in the current context (e.g. a federated account where the password is managed externally). Always show a reason nearby.
+
+### Accessibility
+
+The field must use type=*"password"* in masked state and type=*"text"* in revealed state. Never use type=*"text"* permanently for a password field.
+
+Provide a visible label via <label for> or aria-labelledby. Do not use placeholder as the only label.
+
+Use autocomplete=*"current-password"* or autocomplete=*"new-password"* as appropriate — required for WCAG 1.3.5 (Identify Input Purpose).
+
+The visibility toggle icon button must have a dynamic aria-label reflecting current state: *"Show password"* or *"Hide password"*. It must also have aria-pressed (or aria-expanded) set appropriately, or use aria-label alone to communicate the current action.
+
+When the field transitions to Visibility=True, announce the change to screen readers using aria-live=*"polite"* on a visually hidden region (e.g. *"Password is now visible"*).
+
+The remove button (✕) must have aria-label=*"Clear password"*.
+
+The check icon (✓) is status feedback — it must be wrapped in an aria-live=*"polite"* region that announces *"Passwords match"* when it appears and *"Passwords do not match"* when it disappears.
+
+When State=Error, the error message must be associated via aria-describedby so screen readers announce it when the field receives focus.
+
+When State=Disable, the field must have aria-disabled=*"true"*.
+
+The visibility toggle must be keyboard-operable: Tab to focus, Enter/Space to activate.
+<!-- END:xui-mcp-instructions:input-password -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-password",
-  "version": "0.174.2",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,9 +13,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.2",
-    "@xsolla/xui-icons-base": "0.174.2",
-    "@xsolla/xui-primitives-core": "0.174.2"
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-icons-base": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",