### Install and Run Express Backend

Source: https://github.com/akankov/sentinel-password/blob/main/examples/express-backend/README.md

Commands to install dependencies and start the Express backend development server.

```bash
pnpm install
pnpm --filter express-backend dev
```

--------------------------------

### Run Vite Development Server

Source: https://github.com/akankov/sentinel-password/blob/main/examples/vite-react/README.md

Starts the development server for the Vite + React example. Access the app at http://localhost:5173.

```bash
pnpm --filter vite-react dev
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/akankov/sentinel-password/blob/main/examples/nextjs/README.md

Starts the Next.js development server for the example application. Access the app at http://localhost:3000.

```bash
pnpm --filter nextjs dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/akankov/sentinel-password/blob/main/examples/playground/README.md

Run this command from the repo root to install dependencies for the playground.

```bash
pnpm install
```

--------------------------------

### Install React Packages

Source: https://github.com/akankov/sentinel-password/blob/main/README.md

Install the necessary packages for React integration.

```bash
pnpm add @sentinel-password/react @sentinel-password/react-components
```

--------------------------------

### Install @sentinel-password/core

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Install the core library using npm, pnpm, or yarn.

```bash
npm install @sentinel-password/core
```

```bash
pnpm add @sentinel-password/core
```

```bash
yarn add @sentinel-password/core
```

--------------------------------

### Install Core Package with bun

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the core validation engine with bun.

```bash
bun add @sentinel-password/core
```

--------------------------------

### Install Core Package

Source: https://github.com/akankov/sentinel-password/blob/main/README.md

Install the core validation engine using pnpm or npm.

```bash
pnpm add @sentinel-password/core
# or
npm install @sentinel-password/core
```

--------------------------------

### Run Development Server

Source: https://github.com/akankov/sentinel-password/blob/main/examples/playground/README.md

Execute this command from the repo root to start the playground's development server.

```bash
pnpm --filter playground dev
```

--------------------------------

### Install Core Package with yarn

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the core validation engine with yarn.

```bash
yarn add @sentinel-password/core
```

--------------------------------

### Install Sentinel Password Core

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/getting-started.md

Install the core package for vanilla JavaScript projects using npm.

```bash
npm install @sentinel-password/core
```

--------------------------------

### Install @sentinel-password/react

Source: https://github.com/akankov/sentinel-password/blob/main/packages/react/README.md

Install the package using npm, pnpm, or yarn. The core package is included as a regular dependency.

```bash
npm install @sentinel-password/react
# or
pnpm add @sentinel-password/react
# or
yarn add @sentinel-password/react
```

--------------------------------

### Install @sentinel-password/core with pnpm, npm, or yarn

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/server-side.md

Install the core package on your server. Skip React packages as they are for client-side rendering.

```bash
pnpm add @sentinel-password/core
```

```bash
npm install @sentinel-password/core
```

```bash
yarn add @sentinel-password/core
```

--------------------------------

### Running Benchmarks Locally

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/performance.md

Clone the repository, install dependencies, and run the benchmark command to reproduce performance tests on your local machine.

```bash
git clone https://github.com/akankov/sentinel-password.git
cd sentinel-password
pnpm install
pnpm --filter @sentinel-password/core bench
```

--------------------------------

### Verify Core Package Installation

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Verify the installation of the core package by importing and using the `validatePassword` function.

```javascript
import { validatePassword } from '@sentinel-password/core'

const result = validatePassword('Test-Pa55word!', { minLength: 8 })

console.log(result.valid) // true
console.log(result.strength) // 'very-strong'
```

--------------------------------

### Install Core Package with pnpm

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the core validation engine with pnpm.

```bash
pnpm add @sentinel-password/core
```

--------------------------------

### Install @sentinel-password/react-components

Source: https://github.com/akankov/sentinel-password/blob/main/packages/react-components/README.md

Install the package using npm, pnpm, or yarn. The core package is included as a regular dependency.

```bash
npm install @sentinel-password/react-components
# or
pnpm add @sentinel-password/react-components
# or
yarn add @sentinel-password/react-components
```

--------------------------------

### Install React Components Package with bun

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the headless React password input component with bun.

```bash
bun add @sentinel-password/react-components
```

--------------------------------

### Install Sentinel Password React Components

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/getting-started.md

Install the React components package for pre-built UI elements using npm.

```bash
npm install @sentinel-password/react-components
```

--------------------------------

### Install React Hook Package with bun

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the React hook for password validation with bun.

```bash
bun add @sentinel-password/react
```

--------------------------------

### Password Policy Configuration Examples

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/configuration.md

Examples of password policy configurations, illustrating a too restrictive policy versus a better balanced approach.

```typescript
// Too restrictive — blocks reasonable passwords
{
  minLength: 32,
  maxLength: 32,
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSymbol: true,
}

// Better balance
{
  minLength: 12,
  maxLength: 128,
  requireUppercase: true,
  requireDigit: true,
  requireSymbol: true,
}
```

--------------------------------

### Install React Hook Package with yarn

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the React hook for password validation with yarn.

```bash
yarn add @sentinel-password/react
```

--------------------------------

### Install React Components Package with yarn

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the headless React password input component with yarn.

```bash
yarn add @sentinel-password/react-components
```

--------------------------------

### Install React Components Package with pnpm

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the headless React password input component with pnpm.

```bash
pnpm add @sentinel-password/react-components
```

--------------------------------

### Complete Accessible Example with React

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

A comprehensive example demonstrating how to build an accessible form using React, including proper label association, ARIA attributes, and focus management.

```typescript
import { PasswordInput } from '@sentinel-password/react-components'

function AccessibleSignupForm() {
  return (
    <form>
      <h1>Create Account</h1>
      
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          required
          aria-required="true"
        />
      </div>
      
      <PasswordInput
        label="Password"
        description="At least 8 characters; avoids common passwords and obvious patterns"
        containerClassName="password-field"
        className="password-input"
      />
      
      <button type="submit">
        Create Account
      </button>
      
      <style jsx>{`
        .password-input:focus {
          outline: 2px solid #3c8772;
          outline-offset: 2px;
        }
        
        @media (prefers-reduced-motion: reduce) {
          * {
            animation: none !important;
            transition: none !important;
          }
        }
      `}</style>
    </form>
  )
}
```

--------------------------------

### Install React Hook Package with pnpm

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this command to install the React hook for password validation with pnpm.

```bash
pnpm add @sentinel-password/react
```

--------------------------------

### Local Development Commands

Source: https://github.com/akankov/sentinel-password/blob/main/README.md

Common commands for local development, including installation, building, testing, linting, formatting, and type checking.

```bash
pnpm install
pnpm build         # Build all packages
pnpm test          # Run all tests
pnpm lint          # Run ESLint (does NOT run Prettier — see format:check)
pnpm format:check  # Run Prettier --check
pnpm typecheck     # TypeScript strict mode check
pnpm docs:dev      # Dev docs site
```

--------------------------------

### Signup Form Password Validation Example

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Integrate password validation directly into a signup form handler. This example checks for minimum length, character types, and personal information derived from form data.

```typescript
import { validatePassword } from '@sentinel-password/core'

function handleSignup(formData: {
  email: string
  username: string
  password: string
}) {
  const result = validatePassword(formData.password, {
    minLength: 10,
    requireUppercase: true,
    requireLowercase: true,
    requireDigit: true,
    personalInfo: [formData.email, formData.username]
  })
  
  if (!result.valid) {
    return {
      success: false,
      errors: result.feedback.suggestions
    }
  }
  
  return {
    success: true,
    passwordStrength: result.strength
  }
}
```

--------------------------------

### Install Sentinel Password React Hook

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/getting-started.md

Install the React hook package for React applications using npm.

```bash
npm install @sentinel-password/react
```

--------------------------------

### Basic Validation Examples

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Demonstrates basic password validation for both valid and invalid cases. Shows how to access the warning message for invalid passwords.

```typescript
import { validatePassword } from '@sentinel-password/core'

// Valid password
const result1 = validatePassword('Tr0ub4dor&3')
console.log(result1.valid) // true
console.log(result1.strength) // 'very-strong'

// Invalid password (too short)
const result2 = validatePassword('pass')
console.log(result2.valid) // false
console.log(result2.feedback.warning) // 'Password must be at least 8 characters'
```

--------------------------------

### TypeScript Type Definitions Example

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Demonstrates how to use the TypeScript type definitions provided by the library for robust type checking in your application.

```typescript
import type {
  ValidationResult,
  ValidatorOptions,
  ValidatorCheck,
  StrengthScore,
  StrengthLabel,
  CheckId
} from '@sentinel-password/core'

const options: ValidatorOptions = {
  minLength: 10,
  requireUppercase: true
}

const result: ValidationResult = validatePassword('test', options)
const score: StrengthScore = result.score // 0 | 1 | 2 | 3 | 4
const strength: StrengthLabel = result.strength // 'very-weak' | 'weak' | ...
```

--------------------------------

### Quick Start: Validate Password

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Import and use the validatePassword function to check password strength and validity. Access detailed feedback and suggestions for improvement.

```typescript
import { validatePassword } from '@sentinel-password/core'

const result = validatePassword('MySecure!Pass_w0rd')

if (result.valid) {
  console.log('Password is valid!')
  console.log(`Strength: ${result.strength}`) // 'very-strong'
  console.log(`Score: ${result.score}`) // 4
} else {
  // `feedback.warning` is always equal to `feedback.suggestions[0]` — the
  // first failure, surfaced for prominent display. Iterate `suggestions`
  // for the full list; the first entry is the warning.
  console.log('Password is invalid')
  result.feedback.suggestions.forEach(suggestion => {
    console.log(`- ${suggestion}`)
  })
}
```

--------------------------------

### Controlled PasswordInput Example

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/api/react-components.md

Illustrates how to use the PasswordInput component in a controlled mode. This requires managing the password state using `useState` and passing the `value` and `onChange` props. The example also includes a submit button that is disabled based on validation results.

```tsx
import { PasswordInput } from '@sentinel-password/react-components'
import { useState } from 'react'
import type { ValidationResult } from '@sentinel-password/core'

function SignupForm() {
  const [password, setPassword] = useState('')
  const [result, setResult] = useState<ValidationResult | undefined>()

  return (
    <form>
      <PasswordInput
        label="Create Password"
        value={password}
        onChange={setPassword}
        onValidationChange={setResult}
      />

      <button type="submit" disabled={!result?.valid">
        Create Account
      </button>
    </form>
  )
}
```

--------------------------------

### Conventional Commit Example

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Follow this format for commit messages to ensure consistency and clarity in project history. It includes a type, scope, subject, body, and footer for referencing issues.

```text
feat: add keyboard pattern detection validator

Implements detection of common keyboard patterns like "qwerty" and
"asdfgh" to improve password strength validation.

Closes #123
```

--------------------------------

### Support High Contrast Mode

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

Adapt styles for users with high contrast settings enabled, typically via the `prefers-contrast` media query. This example adds borders and outlines using `currentColor` for better visibility.

```css
@media (prefers-contrast: high) {
  input {
    border: 2px solid currentColor;
  }
  
  input:focus {
    outline: 3px solid currentColor;
  }
}
```

--------------------------------

### Example: Strong Password Policy Configuration

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/getting-started.md

Configure the `validatePassword` function with a strict policy including minimum length, required character types, and disabling certain checks like common passwords.

```typescript
const config = {
  minLength: 12,
  maxLength: 128,
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSymbol: true,
  maxRepeatedChars: 2,
  checkSequential: true,
  checkKeyboardPatterns: true,
  checkCommonPasswords: true,
  personalInfo: ['john', 'doe', 'john@example.com']
}

const result = validatePassword('MySecureP@ssw0rd2024!', config)
```

--------------------------------

### Provide Solutions with Error Messages

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

When reporting an error, also provide a clear solution or suggestion for how the user can resolve the issue. This example shows an error message that includes a recommendation for strengthening the password.

```typescript
// ❌ Problem only
"Password is too weak"

// ✅ Problem + solution
"Password is too weak. Add uppercase letters, numbers, or symbols to strengthen it"
```

--------------------------------

### Provide Meaningful Labels for Password Inputs

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

Always associate a clear and descriptive label with password input fields. This example shows a good practice using a `label` prop and a `description` for user guidance.

```tsx
// ✅ Good
<PasswordInput
  label="Create Password"
  description="At least 8 characters; avoids common passwords and obvious patterns"
/>

// ❌ Bad (no label)
<input type="password" />
```

--------------------------------

### Apply Visible Focus Indicators with CSS

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

Ensure that focus states for input elements are clearly visible to users navigating with a keyboard. This example provides CSS rules for `input:focus` using `outline` and `box-shadow`.

```css
input:focus {
  outline: 2px solid #3c8772;
  outline-offset: 2px;
}

/* Or use box-shadow */
input:focus {
  outline: none;
  box-shadow: 0 0 0 3px rgba(60, 135, 114, 0.3);
}
```

--------------------------------

### Real-time Password Strength Feedback

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/examples/index.md

Use the `usePasswordValidator` hook to provide instant feedback on password strength and validity. This example visualizes the strength using a progress bar and displays specific suggestions for improvement.

```tsx
import { usePasswordValidator } from '@sentinel-password/react'

function PasswordWithStrength() {
  const { password, setPassword, result } = usePasswordValidator({
    minLength: 8,
    requireUppercase: true,
    requireDigit: true,
    requireSymbol: true,
  })

  const score = result?.score ?? 0
  const widthPct = ((score + 1) / 5) * 100

  const color =
    score <= 1 ? 'bg-red-500' : score === 2 ? 'bg-yellow-500' : 'bg-green-500'

  return (
    <div>
      <label htmlFor="pw">Password</label>
      <input
        id="pw"
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />

      <div className="w-full h-2 bg-gray-200 rounded-full mt-2">
        <div
          className={`h-full rounded-full transition-all ${color}`}
          style={{ width: `${widthPct}%` }}
        />
      </div>

      <p className="mt-1 text-sm text-gray-600">
        Strength: <span className="font-semibold">{result?.strength ?? '—'}</span>
      </p>

      {result && !result.valid && (
        <ul className="mt-2 space-y-1">
          {result.feedback.suggestions.map((msg, i) => (
            <li key={i} className="text-sm text-red-600">
              ✗ {msg}
            </li>
          ))}
        </ul>
      )}

      {result?.valid && password && (
        <p className="mt-2 text-sm text-green-600">✓ Password meets all requirements</p>
      )}
    </div>
  )
}
```

--------------------------------

### Build for Production

Source: https://github.com/akankov/sentinel-password/blob/main/examples/playground/README.md

Run this command from the repo root to build the playground for production.

```bash
pnpm --filter playground build
```

--------------------------------

### Build all packages

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Build all packages in the workspace.

```bash
pnpm build
```

--------------------------------

### Preview Production Build

Source: https://github.com/akankov/sentinel-password/blob/main/examples/playground/README.md

Use this command to preview the production build of the playground.

```bash
pnpm --filter playground preview
```

--------------------------------

### Auto-format with Prettier

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Automatically format the codebase using Prettier.

```bash
pnpm format
```

--------------------------------

### validatePassword()

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/api/core.md

Run all built-in checks against a password and get a structured result with strength, feedback, and per-check booleans.

```APIDOC
## validatePassword()

### Description
Run all built-in checks against a password and get a structured result with strength, feedback, and per-check booleans.

### Signature
```typescript
function validatePassword(
  password: string,
  options?: ValidatorOptions
): ValidationResult
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **password** (string) - Required - The password to validate
- **options** (ValidatorOptions) - Optional - Optional validation configuration (all fields optional)

### Request Example
```typescript
import { validatePassword } from '@sentinel-password/core'

const result = validatePassword('MyP@ssw0rd!', {
  minLength: 8,
  maxLength: 128,
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSymbol: true,
})

console.log(result.valid)              // true
console.log(result.strength)           // 'very-strong'
console.log(result.score)              // 4
console.log(result.feedback.warning)   // undefined when valid
console.log(result.feedback.suggestions) // []
console.log(result.checks)
// {
//   length: true, characterTypes: true, repetition: true,
//   sequential: true, keyboardPattern: true,
//   commonPassword: true, personalInfo: true,
// }
```

### Response
#### Success Response (200)
- **ValidationResult** - The result of the password validation, including validity, strength, score, feedback, and individual check statuses.
```

--------------------------------

### Clone the repository

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/sentinel-password.git
cd sentinel-password
```

--------------------------------

### Strong Password Response

Source: https://github.com/akankov/sentinel-password/blob/main/examples/express-backend/README.md

Example JSON response when a strong password is submitted. It indicates success with the password's strength and score.

```json
{ "ok": true, "strength": "very-strong", "score": 4 }
```

--------------------------------

### Weak Password Response

Source: https://github.com/akankov/sentinel-password/blob/main/examples/express-backend/README.md

Example JSON response when a weak password is submitted. It includes details about the failure, strength, score, and suggestions.

```json
{
  "ok": false,
  "strength": "weak",
  "score": 1,
  "warning": "Password must be at least 12 characters",
  "suggestions": ["..."],
  "checks": { "length": false, "characterTypes": false, "...": "..." }
}
```

--------------------------------

### Translate Strength Labels

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/i18n.md

Translate the typed enum for password strength into user-facing strings in your UI layer. This example uses Spanish labels.

```typescript
const strengthLabels = {
  'very-weak': 'Muy débil',
  weak: 'Débil',
  medium: 'Media',
  strong: 'Fuerte',
  'very-strong': 'Muy fuerte',
} as const

<span>{strengthLabels[result.strength]}</span>
```

--------------------------------

### Programmatic Password Update

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/api/react.md

Update the password programmatically using the setPassword function provided by the hook. This example demonstrates generating a random password and setting it.

```tsx
function PasswordGenerator() {
  const { password, setPassword, result } = usePasswordValidator({
    minLength: 12,
    requireUppercase: true,
    requireDigit: true,
    requireSymbol: true,
  })

  const generate = () => {
    setPassword(crypto.randomUUID().slice(0, 12) + 'A1!')
  }

  return (
    <div>
      <button onClick={generate}>Generate</button>
      <p>Generated: {password}</p>
      <p>Strength: {result?.strength}</p>
    </div>
  )
}
```

--------------------------------

### Import Core Package for ESM and CommonJS

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Demonstrates how to import the core package using both ESM and CommonJS module formats.

```javascript
// ESM
import { validatePassword } from '@sentinel-password/core'

// CommonJS
const { validatePassword } = require('@sentinel-password/core')
```

--------------------------------

### Handle Pluralization with IntlMessageFormat

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/i18n.md

Use formatMessage with an ICU-capable library for locales requiring pluralization. This example shows Russian pluralization for a minimum length error.

```typescript
import { IntlMessageFormat } from 'intl-messageformat'

validatePassword(password, {
  formatMessage: (code, params, defaultMessage) => {
    const messageById: Record<string, string> = {
      'length.tooShort':
        '{minLength, plural, one {Минимум # символ} few {Минимум # символа} other {Минимум # символов}}',
    }
    const tmpl = messageById[code]
    if (!tmpl) return defaultMessage
    return new IntlMessageFormat(tmpl, 'ru').format(params) as string
  },
})
```

--------------------------------

### Run all tests

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Execute all tests across the entire workspace.

```bash
pnpm test
```

--------------------------------

### Secure Account Creation with Password Hashing

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/server-side.md

Demonstrates a secure account creation flow by first validating the password strength with Sentinel Password and then hashing it using Argon2id before storing it. This ensures passwords are not stored in plaintext and are protected against common attacks.

```typescript
import argon2 from 'argon2'
import { validatePassword } from '@sentinel-password/core'

async function createAccount(email: string, name: string, password: string) {
  const result = validatePassword(password, {
    minLength: 12,
    requireUppercase: true,
    requireDigit: true,
    requireSymbol: true,
    personalInfo: [email, name],
  })
  if (!result.valid) {
    throw new Error(result.feedback.warning ?? 'Password too weak')
  }

  const hash = await argon2.hash(password, { type: argon2.argon2id })
  await db.users.insert({ email, name, passwordHash: hash })
}
```

--------------------------------

### Using Individual Password Validators

Source: https://github.com/akankov/sentinel-password/blob/main/packages/core/README.md

Import and use individual validation functions for fine-grained control over password checks. This example shows how to use `validateLength` and `validateCharacterTypes`.

```typescript
import {
  validateLength,
  validateCharacterTypes,
  validateRepetition,
  validateSequential,
  validateKeyboardPattern,
  validateCommonPassword,
  validatePersonalInfo
} from '@sentinel-password/core'

const password = 'MyPassword123'

// Check individual constraints
const lengthCheck = validateLength(password, { minLength: 12 })
console.log(lengthCheck.passed) // false
console.log(lengthCheck.message) // 'Password must be at least 12 characters'

const charTypeCheck = validateCharacterTypes(password, {
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSymbol: true,
})
console.log(charTypeCheck.passed) // false
console.log(charTypeCheck.message) // 'Password must contain at least one symbol'
// (one combined message listing every missing type — not one message per type)
```

--------------------------------

### CDN Usage for Core Package (ESM)

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/installation.md

Use this script tag for quick prototyping with the core package via a CDN. Not recommended for production.

```html
<!-- ESM -->
<script type="module">
  import { validatePassword } from 'https://esm.sh/@sentinel-password/core'

  const result = validatePassword('password123', { minLength: 8 })
  console.log(result.valid, result.strength)
</script>
```

--------------------------------

### PasswordInput Validation Message Styling

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/api/react-components.md

Example CSS rules to style validation messages based on their severity. Use the `data-severity` attribute applied to list items.

```css
li[data-severity='warning'] { color: orange; }
li[data-severity='error']   { color: red; }
```

--------------------------------

### Announce Errors with aria-live

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/accessibility.md

Use `aria-live='polite'` on a container for error messages to ensure screen readers announce them to the user. This example demonstrates how to structure an error announcement.

```typescript
<div role="alert" aria-live="polite">
  <p>Password must be at least 8 characters long</p>
</div>
```

--------------------------------

### Basic PasswordInput Usage

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/api/react-components.md

Demonstrates the basic usage of the PasswordInput component for creating a password field with a label and description. It also shows how to use the `onValidationChange` prop to log validation results.

```tsx
import { PasswordInput } from '@sentinel-password/react-components'

function SignupForm() {
  return (
    <form>
      <PasswordInput
        label="Create Password"
        description="At least 8 characters"
        onValidationChange={(result) => console.log(result.strength)}
      />
    </form>
  )
}
```

--------------------------------

### Localized Password Input with Custom Messages

Source: https://context7.com/akankov/sentinel-password/llms.txt

Example of using PasswordInput with custom validation messages for localization. It demonstrates how to override default messages using the `messages` option within `validatorOptions`.

```tsx
import { PasswordInput } from '@sentinel-password/react-components'
import type { ValidationResult } from '@sentinel-password/core'
import { useState, useMemo } from 'react'

// --- Localized component with i18n ---
function LocalizedPasswordInput() {
  const validatorOptions = useMemo(() => ({
    minLength: 12,
    messages: {
      'length.tooShort': 'Mínimo {minLength} caracteres',
      'commonPassword.found': 'Contraseña demasiado común',
    },
  }), [])

  return (
    <PasswordInput
      label="Contraseña"
      description="Mínimo 12 caracteres"
      validatorOptions={validatorOptions}
      toggleShowText="Mostrar"
      toggleHideText="Ocultar"
      toggleShowLabel="Mostrar contraseña"
      toggleHideLabel="Ocultar contraseña"
      showValidationMessages={true}
    />
  )
}
```

--------------------------------

### Check ESLint issues

Source: https://github.com/akankov/sentinel-password/blob/main/CONTRIBUTING.md

Run ESLint to check for code style and potential errors.

```bash
pnpm lint
```

--------------------------------

### React Hook Debouncing Example

Source: https://github.com/akankov/sentinel-password/blob/main/packages/docs/docs/guide/performance.md

Demonstrates how to use the `usePasswordValidator` hook in React with built-in debouncing. The `debounceMs` option controls the delay before validation runs after typing stops, defaulting to 300ms.

```typescript
import { usePasswordValidator } from '@sentinel-password/react'

const { password, setPassword, result } = usePasswordValidator({
  minLength: 8,
  debounceMs: 300, // Default — validates 300ms after typing stops
})
```