@xsolla/xui-input-password 0.99.0 → 0.100.0

package/README.md

@@ -1,44 +1,239 @@
-# @xsolla/xui-input-password
+---
+title: Input Password
+subtitle: A password input with visibility toggle.
+description: A cross-platform React password input component with show/hide toggle, validation, and clear button.
+---
 
-Password input with visibility toggle, clear button, and validation check support.
+# Input Password
+
+A cross-platform React password input component with visibility toggle, validation checkmark, and clear functionality.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-input-password
+# or
 yarn add @xsolla/xui-input-password
 ```
 
-## Usage
+## Demo
+
+### Basic Password Input
 
 ```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function BasicPassword() {
+  const [password, setPassword] = React.useState('');
+
+  return (
+    <InputPassword
+      value={password}
+      onChange={(e) => setPassword(e.target.value)}
+      placeholder="Enter password"
+    />
+  );
+}
+```
+
+### With Visibility Toggle
+
+```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function VisibilityToggle() {
+  const [password, setPassword] = React.useState('');
+
+  return (
+    <InputPassword
+      value={password}
+      onChange={(e) => setPassword(e.target.value)}
+      extraSee={true}
+      placeholder="Enter password"
+    />
+  );
+}
+```
+
+### With Validation
+
+```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function PasswordValidation() {
+  const [password, setPassword] = React.useState('');
+
+  return (
+    <InputPassword
+      value={password}
+      onChange={(e) => setPassword(e.target.value)}
+      extraSee={true}
+      extraCheckup={(pass) => pass.length >= 8}
+      label="Password"
+      helperText="At least 8 characters"
+      placeholder="Enter password"
+    />
+  );
+}
+```
+
+### With Error State
+
+```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function PasswordError() {
+  const [password, setPassword] = React.useState('');
+
+  return (
+    <InputPassword
+      value={password}
+      onChange={(e) => setPassword(e.target.value)}
+      extraSee={true}
+      error={password.length > 0 && password.length < 8}
+      errorMessage="Password must be at least 8 characters"
+      label="Password"
+      placeholder="Enter password"
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
 import { InputPassword } from '@xsolla/xui-input-password';
 
 <InputPassword
-  label="Password"
-  placeholder="Enter password"
-  extraSee
-  extraClear
-  value={value}
-  onChange={(e) => setValue(e.target.value)}
-  errorMessage="Password is too short"
+  value={password}              // Controlled value
+  onChange={handleChange}       // Change handler (event)
+  onChangeText={handleText}     // Change handler (string)
+  extraSee={true}               // Show visibility toggle
+  extraClear={true}             // Show clear button
+  extraCheckup={validateFn}     // Validation function
+  label="Label"                 // Label above input
+  helperText="Help text"        // Helper text below
+  error={boolean}               // Error state
+  errorMessage="Error"          // Error message
+  size="md"                      // Size variant
+  disabled={false}              // Disabled state
 />
 ```
 
-## Props
+## Examples
+
+### Full Featured Password
+
+```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function FullPassword() {
+  const [password, setPassword] = React.useState('');
+  const [error, setError] = React.useState('');
+
+  const validatePassword = (pass: string) => {
+    if (pass.length < 8) return false;
+    if (!/[A-Z]/.test(pass)) return false;
+    if (!/[0-9]/.test(pass)) return false;
+    return true;
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value;
+    setPassword(value);
+    if (value && !validatePassword(value)) {
+      setError('Password must be 8+ chars with uppercase and number');
+    } else {
+      setError('');
+    }
+  };
+
+  return (
+    <InputPassword
+      value={password}
+      onChange={handleChange}
+      extraSee={true}
+      extraClear={true}
+      extraCheckup={validatePassword}
+      onRemove={() => setPassword('')}
+      label="Password"
+      helperText="8+ characters, uppercase, and number required"
+      error={!!error}
+      errorMessage={error}
+      placeholder="Create a strong password"
+    />
+  );
+}
+```
+
+### Password Sizes
+
+```tsx
+import * as React from 'react';
+import { InputPassword } from '@xsolla/xui-input-password';
+
+export default function PasswordSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <InputPassword size="xs" placeholder="Extra Small" extraSee />
+      <InputPassword size="sm" placeholder="Small" extraSee />
+      <InputPassword size="md" placeholder="Medium" extraSee />
+      <InputPassword size="lg" placeholder="Large" extraSee />
+      <InputPassword size="xl" placeholder="Extra Large" extraSee />
+    </div>
+  );
+}
+```
+
+## API Reference
 
 ### InputPassword
 
+**InputPassword Props:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | — | Controlled value |
-| `placeholder` | `string` | — | Placeholder text |
-| `onChange` | `(e: ChangeEvent) => void` | — | Change handler |
-| `onChangeText` | `(text: string) => void` | — | Alternative change handler receiving the string value |
-| `size` | `'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs'` | `'md'` | Input size |
-| `disabled` | `boolean` | `false` | Disables the input |
-| `label` | `string` | — | Label displayed above the input |
-| `helperText` | `string` | — | Helper text below the input (hidden when `errorMessage` is set) |
-| `errorMessage` | `string` | — | Error text displayed below; also sets invalid state |
-| `error` | `boolean` | — | Sets invalid state without a message |
-| `extraSee` | `boolean` | `false` | Shows a visibility toggle button |
-| `extraClear` | `boolean` | `false` | Shows a clear button when the field has a value |
+| :--- | :--- | :------ | :---------- |
+| value | `string` | - | Controlled input value. |
+| onChange | `(e: ChangeEvent) => void` | - | Change event handler. |
+| onChangeText | `(text: string) => void` | - | Text change handler. |
+| extraSee | `boolean` | `false` | Show visibility toggle button. |
+| extraClear | `boolean` | `false` | Show clear button. |
+| extraCheckup | `(pass: string) => boolean` | - | Validation function. |
+| initialVisible | `boolean` | `false` | Initial password visibility. |
+| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Component size. |
+| label | `string` | - | Label above input. |
+| helperText | `string` | - | Helper text below input. |
+| error | `boolean` | `false` | Error state. |
+| errorMessage | `string` | - | Error message. |
+| disabled | `boolean` | `false` | Disabled state. |
+| placeholder | `string` | - | Placeholder text. |
+| name | `string` | - | Input name attribute. |
+| onRemove | `() => void` | - | Clear button handler. |
+| aria-label | `string` | - | Accessible label. |
+| testID | `string` | - | Test identifier. |
+
+## Behavior
+
+- **Visibility Toggle**: The eye icon reflects the current state of the password:
+  - Open eye (👁️) = Password is currently **visible** (type="text")
+  - Closed eye (🙈) = Password is currently **hidden** (type="password")
+  - This follows modern design system conventions (Material, Apple, Atlassian, Polaris)
+- Checkmark appears when `extraCheckup` returns true
+- Clear button appears when input has value and `extraClear` is true
+- Error state shows red border and error message
+
+## Accessibility
+
+- Uses `type="password"` or `type="text"` based on visibility
+- Visibility toggle button has appropriate `aria-label`:
+  - "Show password" when password is hidden
+  - "Hide password" when password is visible
+- Toggle button uses `aria-pressed` to indicate current state
+- Error messages linked via `aria-describedby` for screen reader context
+- Labels properly linked via `aria-labelledby` when provided
+- Error messages use `role="alert"` for immediate announcement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-input-password",
-  "version": "0.99.0",
+  "version": "0.100.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.99.0",
-    "@xsolla/xui-icons": "0.99.0",
-    "@xsolla/xui-primitives-core": "0.99.0"
+    "@xsolla/xui-core": "0.100.0",
+    "@xsolla/xui-icons": "0.100.0",
+    "@xsolla/xui-primitives-core": "0.100.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",