@delightui/components 0.1.104 → 0.1.106

package/docs/components/atoms/Password.md

@@ -0,0 +1,472 @@
+# Password
+
+A specialized input component designed specifically for password entry. It extends the Input component with built-in password visibility toggle functionality, providing a secure and user-friendly way to handle password inputs. The component automatically includes a show/hide password toggle icon unless explicitly disabled.
+
+## Aliases
+
+- Password
+- PasswordInput
+- SecureInput
+
+## Props Breakdown
+
+**Extends:** `InputHTMLAttributes<HTMLInputElement>` (via InputProps, excluding `inputType`, `trailingIcon`) + `ControlledFormComponentProps<string>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `hideTrailingIcon` | `boolean` | `false` | No | Whether to hide the password visibility toggle icon |
+| `leadingIcon` | `ReactNode` | `undefined` | No | Icon to be displayed before the input |
+| `component-variant` | `string` | `undefined` | No | Override styling variant |
+| `initialValue` | `string` | `undefined` | No | The initial value for the field |
+| `checked` | `boolean` | `undefined` | No | The initial value for the field |
+| `value` | `string` | `undefined` | No | The current value of the form field |
+| `onValueChange` | `(value: string) => void` | `undefined` | No | Callback function that is called when the field value changes |
+| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
+| `required` | `boolean` | `false` | No | Whether the form field must have a value |
+| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
+| `id` | `string` | `undefined` | No | Id for the form field |
+| `placeholder` | `string` | `undefined` | No | Placeholder text for the input |
+| `maxLength` | `number` | `undefined` | No | Maximum length of the input value |
+| `minLength` | `number` | `undefined` | No | Minimum length of the input value |
+| `readOnly` | `boolean` | `false` | No | Whether the input is read-only |
+| `autoComplete` | `string` | `undefined` | No | Autocomplete attribute for the input |
+| `autoFocus` | `boolean` | `false` | No | Whether the input should be focused on mount |
+
+Plus all standard HTML input attributes (name, onChange, onFocus, onBlur, etc.).
+
+## Examples
+
+### Basic Password Input
+
+```tsx
+import { Password } from '@delightui/components';
+
+function BasicPasswordExample() {
+  const [password, setPassword] = useState('');
+
+  return (
+    <Password
+      value={password}
+      onValueChange={setPassword}
+      placeholder="Enter your password"
+    />
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, Password, Button } from '@delightui/components';
+
+function PasswordFormExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="password"
+        label="Password"
+        required
+      >
+        <Password
+          placeholder="Enter your password"
+          autoComplete="current-password"
+        />
+      </FormField>
+
+      <Button type="submit">
+        Sign In
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Password with Leading Icon
+
+```tsx
+import { Password, Icon } from '@delightui/components';
+
+function PasswordWithIconExample() {
+  const [password, setPassword] = useState('');
+
+  return (
+    <Password
+      value={password}
+      onValueChange={setPassword}
+      placeholder="Enter your password"
+      leadingIcon={<Icon name="InfoFilled" />}
+    />
+  );
+}
+```
+
+### Password without Toggle Icon
+
+```tsx
+import { Password } from '@delightui/components';
+
+function PasswordWithoutToggleExample() {
+  const [password, setPassword] = useState('');
+
+  return (
+    <Password
+      value={password}
+      onValueChange={setPassword}
+      placeholder="Enter your password"
+      hideTrailingIcon={true}
+    />
+  );
+}
+```
+
+### Registration Form with Password Confirmation
+
+```tsx
+import { Form, FormField, Password, Button, Text } from '@delightui/components';
+
+function RegistrationFormExample() {
+  const [formData, setFormData] = useState({
+    password: '',
+    confirmPassword: ''
+  });
+
+  const [passwordMatch, setPasswordMatch] = useState(true);
+
+  const handlePasswordChange = (value: string) => {
+    setFormData(prev => ({ ...prev, password: value }));
+    setPasswordMatch(value === formData.confirmPassword || formData.confirmPassword === '');
+  };
+
+  const handleConfirmPasswordChange = (value: string) => {
+    setFormData(prev => ({ ...prev, confirmPassword: value }));
+    setPasswordMatch(formData.password === value || value === '');
+  };
+
+  const handleSubmit = (data: any) => {
+    if (passwordMatch) {
+      console.log('Registration data:', data);
+    }
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="password"
+        label="Password"
+        required
+        message="Password must be at least 8 characters long"
+      >
+        <Password
+          value={formData.password}
+          onValueChange={handlePasswordChange}
+          placeholder="Enter your password"
+          minLength={8}
+          autoComplete="new-password"
+        />
+      </FormField>
+
+      <FormField
+        name="confirmPassword"
+        label="Confirm Password"
+        required
+        invalid={!passwordMatch}
+        message={!passwordMatch ? "Passwords do not match" : undefined}
+      >
+        <Password
+          value={formData.confirmPassword}
+          onValueChange={handleConfirmPasswordChange}
+          placeholder="Confirm your password"
+          invalid={!passwordMatch}
+          autoComplete="new-password"
+        />
+      </FormField>
+
+      {!passwordMatch && (
+        <Text color="error" size="small">
+          Passwords must match
+        </Text>
+      )}
+
+      <Button 
+        type="submit" 
+        disabled={!passwordMatch || !formData.password || !formData.confirmPassword}
+      >
+        Create Account
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Password Strength Indicator
+
+```tsx
+import { Password, Text } from '@delightui/components';
+
+function PasswordStrengthExample() {
+  const [password, setPassword] = useState('');
+  const [strength, setStrength] = useState({ score: 0, text: 'Weak', color: 'error' });
+
+  const evaluatePasswordStrength = (pwd: string) => {
+    let score = 0;
+    
+    if (pwd.length >= 8) score++;
+    if (/[a-z]/.test(pwd)) score++;
+    if (/[A-Z]/.test(pwd)) score++;
+    if (/[0-9]/.test(pwd)) score++;
+    if (/[^A-Za-z0-9]/.test(pwd)) score++;
+
+    const strength = {
+      0: { text: 'Very Weak', color: 'error' },
+      1: { text: 'Weak', color: 'error' },
+      2: { text: 'Fair', color: 'warning' },
+      3: { text: 'Good', color: 'info' },
+      4: { text: 'Strong', color: 'success' },
+      5: { text: 'Very Strong', color: 'success' }
+    };
+
+    return { score, ...strength[score as keyof typeof strength] };
+  };
+
+  const handlePasswordChange = (value: string) => {
+    setPassword(value);
+    setStrength(evaluatePasswordStrength(value));
+  };
+
+  return (
+    <div>
+      <Password
+        value={password}
+        onValueChange={handlePasswordChange}
+        placeholder="Enter a strong password"
+      />
+      
+      {password && (
+        <div style={{ marginTop: '8px' }}>
+          <div style={{
+            height: '4px',
+            backgroundColor: '#e0e0e0',
+            borderRadius: '2px',
+            overflow: 'hidden'
+          }}>
+            <div
+              style={{
+                height: '100%',
+                width: `${(strength.score / 5) * 100}%`,
+                backgroundColor: 
+                  strength.color === 'error' ? '#dc3545' :
+                  strength.color === 'warning' ? '#ffc107' :
+                  strength.color === 'info' ? '#17a2b8' :
+                  '#28a745',
+                transition: 'all 0.3s ease'
+              }}
+            />
+          </div>
+          
+          <Text size="small" color={strength.color} style={{ marginTop: '4px' }}>
+            Password Strength: {strength.text}
+          </Text>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Disabled Password Input
+
+```tsx
+import { Password } from '@delightui/components';
+
+function DisabledPasswordExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Password
+        value="example-password"
+        disabled
+        placeholder="This field is disabled"
+      />
+      
+      <Password
+        value=""
+        disabled
+        placeholder="Empty disabled field"
+      />
+    </div>
+  );
+}
+```
+
+### Read-Only Password Display
+
+```tsx
+import { Password } from '@delightui/components';
+
+function ReadOnlyPasswordExample() {
+  return (
+    <Password
+      value="hidden-password-value"
+      readOnly
+      placeholder="Read-only password"
+    />
+  );
+}
+```
+
+### Login Form Example
+
+```tsx
+import { Form, FormField, Input, Password, Button, Text } from '@delightui/components';
+
+function LoginFormExample() {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (data: any) => {
+    setIsLoading(true);
+    setError('');
+    
+    try {
+      // Simulate API call
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      console.log('Login successful:', data);
+    } catch (err) {
+      setError('Invalid username or password');
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="username"
+        label="Username"
+        required
+      >
+        <Input
+          placeholder="Enter your username"
+          autoComplete="username"
+        />
+      </FormField>
+
+      <FormField
+        name="password"
+        label="Password"
+        required
+      >
+        <Password
+          placeholder="Enter your password"
+          autoComplete="current-password"
+        />
+      </FormField>
+
+      {error && (
+        <Text color="error" size="small">
+          {error}
+        </Text>
+      )}
+
+      <Button 
+        type="submit" 
+        loading={isLoading}
+        style={{ width: '100%' }}
+      >
+        {isLoading ? 'Signing In...' : 'Sign In'}
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Password Change Form
+
+```tsx
+import { Form, FormField, Password, Button } from '@delightui/components';
+
+function PasswordChangeExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Password change data:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="currentPassword"
+        label="Current Password"
+        required
+      >
+        <Password
+          placeholder="Enter your current password"
+          autoComplete="current-password"
+        />
+      </FormField>
+
+      <FormField
+        name="newPassword"
+        label="New Password"
+        required
+        message="Must be at least 8 characters with uppercase, lowercase, and numbers"
+      >
+        <Password
+          placeholder="Enter your new password"
+          minLength={8}
+          autoComplete="new-password"
+        />
+      </FormField>
+
+      <FormField
+        name="confirmNewPassword"
+        label="Confirm New Password"
+        required
+      >
+        <Password
+          placeholder="Confirm your new password"
+          autoComplete="new-password"
+        />
+      </FormField>
+
+      <Button type="submit">
+        Change Password
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Custom Styled Password
+
+```tsx
+import { Password } from '@delightui/components';
+
+function CustomStyledPasswordExample() {
+  const [password, setPassword] = useState('');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <Password
+        value={password}
+        onValueChange={setPassword}
+        placeholder="Custom styled password"
+        component-variant="custom-password"
+        style={{
+          border: '2px solid #007bff',
+          borderRadius: '8px',
+          padding: '12px'
+        }}
+      />
+      
+      <Password
+        value={password}
+        onValueChange={setPassword}
+        placeholder="Another custom style"
+        className="custom-password-class"
+      />
+    </div>
+  );
+}
+```