use-password-policy 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 3.1.0
+
+### Added
+- **`patternCheck`** rejects predictable passwords: repeated characters (`aaaaaaaaaaaaaaa`), repeated chunks (`qwertyqwertyqwerty`, `dragon dragon dragon`), sequences and keyboard runs (`123456789012345`, `abcdefghijk`), and passwords made of only a few distinct characters, including all spaces. It's on in `presets.nist` and `presets.nistMfa`.
+- **`breachCheck`** puts Have I Been Pwned into the normal result. The hook checks once the other rules pass and adds a `notBreached` requirement that is `pending` until answered. `isValid` waits for it, and the component shows it automatically. `failOpen` decides what happens when the service is down (default: let through).
+- **`validatePasswordAsync()`** for servers, with the same result plus the breach check. Also `zodPasswordRuleAsync()`, `passwordValidatorAsync()` and `applyBreachResult()`.
+- Results include `breach: { status, count }`, and requirements can be `pending`.
+- `isPredictablePattern()` and `passwordLength()` helpers.
+
+### Fixed
+- Length rules count Unicode code points, as NIST specifies. 8 emoji no longer pass a 15-character minimum.
+- The common-password check now catches list words joined together (`passwordpassword`, `Summer2024!Summer`).
+- `<PasswordPolicyInput />` calls `onPasswordChange` again when an async check settles.
+- Repeated breach checks for the same hash prefix reuse the previous response.
+
+## 3.0.0
+
+### Added
+- **`use-password-policy/core`**: a framework-free `validatePassword(password, options)` for running the same policy on the server (Node, edge, API routes). It doesn't import React.
+- **Presets**: `presets.nist` and `presets.nistMfa`, following NIST SP 800-63B-4, plus `presets.classic`.
+- **New rules**: `maxLength`, `commonPasswordCheck` (a built-in blocklist that also catches decorated variants like `P@ssw0rd123!`), and `confirmPassword` (a "passwords match" rule).
+- **Breach checks**: `checkPwnedPassword()` and a `usePwnedPassword()` hook using Have I Been Pwned k-anonymity. Only a 5-character hash prefix is sent.
+- **Real strength scoring**: a `strengthEstimator` option and a `fromZxcvbn()` adapter (zxcvbn and @zxcvbn-ts v3/v4), plus `minStrength`.
+- **Integrations**: `zodPasswordRule()` for Zod `superRefine` and `passwordValidator()` for react-hook-form `validate`. Neither adds a dependency.
+- **Messages & i18n**: every requirement has readable text, and `messages` overrides it.
+- The result now includes `requirements`, `errors`, `strengthPercent` and `estimate`.
+- Component: controlled mode (`value`/`onChange`), `ref` forwarding, `inputClassName`, `showStrengthLabel`, `toggleLabels`, `unstyled`, and the `use-password-policy/styles.css` export.
+- Accessibility: `aria-describedby` checklist, `role="meter"`, `aria-invalid`, labelled toggle button, and "met"/"not met" text for screen readers.
+- The React entry is marked `'use client'` for the Next.js App Router.
+- Tests (Vitest + Testing Library), with CI on React 18 and 19.
+
+### Changed (breaking)
+- **Dropped the `styled-components` peer dependency.** The component now ships plain, low-specificity CSS, themeable through the same `--rpp-*` variables.
+- Component DOM and class names changed to `.rpp-*`.
+- `onPasswordChange` no longer fires on mount.
+- `react-dom` is no longer a peer dependency, and `react` is optional (only needed for the hook and component).
+
+### Fixed
+- Passing `onChange` or `value` to `<PasswordPolicyInput />` used to break it. Both now work.
+- The strength meter can now fill completely when fewer than five rules are active.
+- `--rpp-bg` and `--rpp-text` now actually style the input.
+- Options explicitly set to `undefined` no longer override the defaults.
+- The npm README no longer shows leftover placeholder notes. The LICENSE file is added and the license link fixed.
+- The demo deploy workflow now runs on `master`, which was the actual default branch.
+
+## 2.0.0
+- Added the `<PasswordPolicyInput />` component (styled-components) and custom rules.
+
+## 1.x
+- First release of the `usePasswordPolicy` hook.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rahul Patwa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,204 +1,323 @@
 # use-password-policy
 
 [![npm version](https://img.shields.io/npm/v/use-password-policy.svg)](https://www.npmjs.com/package/use-password-policy)
-[![npm downloads](https://img.shields.io/npm/dm/use-password-policy.svg)](https://www.npmjs.com/package/use-password-policy)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![CI](https://github.com/rahulpatwa1303/use-password-policy/actions/workflows/ci.yml/badge.svg)](https://github.com/rahulpatwa1303/use-password-policy/actions/workflows/ci.yml)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/use-password-policy)](https://bundlephobia.com/package/use-password-policy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-A powerful, lightweight, and fully customizable solution for real-time password strength validation in React. Comes with a flexible hook and a zero-config, all-in-one UI component.
+**Write your password rules once. Use them in your React form and on your server.**
 
----
-
-### [➡️ View Live Demo & Playground](https://rahulpatwa1303.github.io/use-password-policy/)
+- A hook and an accessible drop-in `<PasswordPolicyInput />`
+- A framework-free `validatePassword()` for Node, edge functions and API routes
+- A **NIST SP 800-63B** preset, a common-password blocklist and **Have I Been Pwned** breach checks
+- Optional **zxcvbn** scoring, so "strength" means how hard a password is to guess, not how many boxes it ticks
+- **Zod** and **react-hook-form** helpers
+- No runtime dependencies. About 4 KB gzipped for the core, about 6.5 KB with the React parts.
 
-*(Replace this with your final GitHub Pages URL)*
+### [➡️ Live demo & playground](https://rahulpatwa1303.github.io/use-password-policy/)
 
-
-*(**Action Needed:** Record a GIF of your awesome demo and replace this link!)*
+![PasswordPolicyInput demo](https://raw.githubusercontent.com/rahulpatwa1303/use-password-policy/master/.github/assets/demo.gif)
 
 ---
 
-## ✨ Why `use-password-policy`?
-
--   **🚀 Two Ways to Use:** Get full control with the `usePasswordPolicy` hook, or get running in seconds with the drop-in `<PasswordPolicyInput />` component.
--   **🔧 Fully Customizable:** Easily configure policies like min-length, character requirements, and even add your own complex rules with custom functions or regex.
--   **💅 Zero-Config Styling:** The UI component works out-of-the-box with self-contained styles, but is easily overridable.
--   **✅ Rich & Reactive Feedback:** Provides a simple `isValid` boolean, a detailed `policyState` object, and a `strengthScore` to easily build any UI you can imagine.
--   **♿ Accessibility First:** The component is designed with accessibility in mind, ready to be paired with a `<label>`.
--   **📦 Tiny & Performant:** Zero dependencies and built with performance in mind, using `useMemo` to prevent unnecessary recalculations.
-
-## 💾 Installation
+## Install
 
 ```bash
 npm install use-password-policy
-# or
-yarn add use-password-policy
 ```
 
-## 🚀 Usage
-
-You have two great ways to implement password validation.
+React 16.8+ is needed for the hook and component. It is tested on React 18 and 19. The `use-password-policy/core` entry doesn't need React at all.
 
-### 1. The Easy Way: `<PasswordPolicyInput />` Component
+## Quick start
 
-For maximum speed, drop the component directly into your form. It includes the input, strength meter, and requirements list all-in-one.
+### 1. Drop-in component
 
 ```tsx
 import { PasswordPolicyInput } from 'use-password-policy';
 
-function MyForm() {
+function SignUp() {
   const [isValid, setIsValid] = useState(false);
 
   return (
     <form>
-      <label htmlFor="signup-password">Create a Password</label>
+      <label htmlFor="password">Password</label>
       <PasswordPolicyInput
-        id="signup-password"
+        id="password"
         name="password"
-        placeholder="Enter a secure password..."
-        onPasswordChange={(_, validation) => {
-          setIsValid(validation.isValid);
-        }}
-        policyOptions={{ minLength: 8, numberCheck: true, specialCharCheck: true }}
+        policyOptions={{ minLength: 10 }}
+        onPasswordChange={(_, v) => setIsValid(v.isValid)}
       />
-      <button type="submit" disabled={!isValid}>
-        Sign Up
-      </button>
+      <button disabled={!isValid}>Sign up</button>
     </form>
   );
 }
 ```
 
-### 2. The Powerful Way: `usePasswordPolicy` Hook
+The component comes with its own styles, a strength meter, a checklist, and a show/hide button that screen readers can use.
 
-For complete control over your UI, use the hook and build your own components.
+### 2. Hook (build your own UI)
 
 ```tsx
 import { usePasswordPolicy } from 'use-password-policy';
 
-function MyCustomForm() {
-  const [password, setPassword] = useState('');
-  const { isValid, strengthLabel, policyState } = usePasswordPolicy({
-    password: password,
-    minLength: 10,
-    uppercaseCheck: true,
-    customRules: [{ name: 'noSpaces', test: (p) => !/\\s/.test(p) }],
-  });
+const { isValid, requirements, strengthLabel, strengthPercent } = usePasswordPolicy({
+  password,
+  minLength: 10,
+  customRules: [{ name: 'noSpaces', message: 'No spaces', test: (p) => !/\s/.test(p) }],
+});
+
+<ul>
+  {requirements.map((r) => (
+    <li key={r.name} style={{ color: r.passed ? 'green' : 'crimson' }}>{r.message}</li>
+  ))}
+</ul>
+```
+
+### 3. The same policy on the server
 
-  return (
-    <form>
-      <input
-        type="password"
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-      />
-      <div>Strength: {strengthLabel}</div>
-      <ul>
-        {Object.entries(policyState).map(([rule, passed]) => (
-          <li key={rule} style={{ color: passed ? 'green' : 'red' }}>
-            {rule}
-          </li>
-        ))}
-      </ul>
-      <button type="submit" disabled={!isValid}>
-        Submit
-      </button>
-    </form>
-  );
-}
+```ts
+// password-policy.ts — shared by client and server
+import { presets, type PasswordPolicyOptions } from 'use-password-policy/core';
+export const policy: PasswordPolicyOptions = { ...presets.nist, breachCheck: true };
 ```
 
-## 📖 API Reference
+```ts
+// api/sign-up.ts (Node, Next.js route handler, Express, Cloudflare Worker…)
+import { validatePasswordAsync } from 'use-password-policy/core';
+import { policy } from './password-policy';
 
-### `<PasswordPolicyInput />` Props
+const { isValid, errors } = await validatePasswordAsync(body.password, policy);
+if (!isValid) return Response.json({ errors }, { status: 400 });
+```
 
-| Prop                   | Type                                                       | Default | Description                                                               |
-| ---------------------- | ---------------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
-| `policyOptions`        | `PasswordPolicyOptions`                                    | `{}`    | Same options as the `usePasswordPolicy` hook to control validation logic. |
-| `onPasswordChange`     | `(password: string, validation: HookReturnValue) => void`  | `null`  | Callback fired on change, providing the password and full validation state. |
-| `showStrengthMeter`    | `boolean`                                                  | `true`  | Toggles the visibility of the strength meter bar.                         |
-| `showRequirementsList` | `boolean`                                                  | `true`  | Toggles the visibility of the pass/fail requirements list.              |
-| `showToggleButton`     | `boolean`                                                  | `true`  | Toggles the visibility of the show/hide password button.                  |
-| `...restInputProps`    | `React.InputHTMLAttributes`                                |         | All other standard input props (`id`, `name`, `placeholder`, etc.) are passed to the `<input>`. |
+Use `validatePasswordAsync` when the policy has `breachCheck`. Without it, the synchronous `validatePassword` returns the same result.
 
-<br/>
+`use-password-policy/core` doesn't import React, so it's safe in server bundles.
 
-### `usePasswordPolicy` Hook
+## Presets
 
-#### Options (`PasswordPolicyOptions`)
+```ts
+import { presets } from 'use-password-policy';
 
-| Prop                   | Type           | Default    | Description                                                 |
-| ---------------------- | -------------- | ---------- | ----------------------------------------------------------- |
-| `password`             | `string`       | `''`       | The password string to validate.                            |
-| `minLength`            | `number`       | `8`        | Minimum password length.                                    |
-| `lowercaseCheck`       | `boolean`      | `true`     | Requires at least one lowercase letter.                     |
-| `uppercaseCheck`       | `boolean`      | `true`     | Requires at least one uppercase letter.                     |
-| `numberCheck`          | `boolean`      | `true`     | Requires at least one number.                               |
-| `specialCharCheck`     | `boolean`      | `true`     | Requires at least one special character.                    |
-| `customRules`          | `PolicyRule[]` | `[]`       | An array of custom validation rules.                        |
+usePasswordPolicy({ ...presets.nist, password });          // NIST, password used on its own
+usePasswordPolicy({ ...presets.nistMfa, password });       // NIST, password is one factor of MFA
+usePasswordPolicy({ ...presets.classic, password });       // 8+ chars, upper, lower, number, symbol (the default)
+```
 
-#### Return Value (`HookReturnValue`)
+| Preset | Min | Max | Composition rules | Blocks common passwords | Blocks patterns |
+| --- | --- | --- | --- | --- | --- |
+| `classic` (default) | 8 | – | upper, lower, number, symbol | no | no |
+| `nist` | 15 | 64 | none | yes | yes |
+| `nistMfa` | 8 | 64 | none | yes | yes |
 
-| Key             | Type                                                         | Description                                                               |
-| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- |
-| `isValid`       | `boolean`                                                    | `true` only if all active policies are met.                               |
-| `strengthScore` | `number`                                                     | The number of policies that have passed.                                  |
-| `strengthLabel` | `'Very Weak' \| 'Weak' \| 'Medium' \| 'Strong' \| 'Very Strong'` | A human-readable strength label.                                          |
-| `policyState`   | `object`                                                     | An object with boolean flags for each active policy (`{ minLength: true, uppercase: false, ... }`). |
+The NIST presets follow [SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b.html). It asks for length and a blocklist check, and says not to require "mixtures of different character types". Length is counted in Unicode code points, as NIST specifies, so an emoji counts as one character. To also check known breaches, add `breachCheck: true`.
 
-## 🎨 Customizing Styles
+## Security add-ons
 
-The `<PasswordPolicyInput />` component is built with `styled-components` for complete style isolation and easy customization. You have two primary ways to apply your own styles:
+### Block common passwords
 
-### 1. Theming with `styled()`
+```ts
+usePasswordPolicy({ password, commonPasswordCheck: true });
+```
 
-For deep customization, wrap the component with `styled()` from `styled-components`. You can easily change the theme by overriding the internal CSS variables, or target any internal element for specific changes.
+This uses a small built-in list of the most common passwords and base words. It also catches simple variations such as `Password123!`, `P@ssw0rd`, `123qwerty` and `Monkey!!`, and list words joined together such as `passwordpassword` or `Summer2024!Summer`. Pass `commonPasswords: [...]` to use your own list, for example your product name.
 
-```jsx
-import styled from 'styled-components';
-import { PasswordPolicyInput } from 'use-password-policy';
+### Block predictable patterns
 
-const MyStyledInput = styled(PasswordPolicyInput)`
-  /* Override theme variables */
-  --rpp-accent: #ff6347; // Use a tomato red accent
+```ts
+usePasswordPolicy({ password, patternCheck: true });   // on in the NIST presets
+```
+
+Rejects repeated characters (`aaaaaaaaaaaaaaa`), repeated chunks (`qwertyqwertyqwerty`, `dragon dragon dragon`), sequences and keyboard runs (`123456789012345`, `abcdefghijk`, `qwertyuiop`), and passwords made of only a few distinct characters, including all spaces.
 
-  /* Override specific elements */
-  input {
-    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-  }
-`;
+### Check breached passwords (Have I Been Pwned)
 
-// Then use <MyStyledInput /> in your app!
+```tsx
+const { isValid, requirements, breach } = usePasswordPolicy({ ...presets.nist, breachCheck: true, password });
 ```
 
-**Available CSS Variables for Theming:**
+With `breachCheck`, the check is part of the normal result:
+- Once every other rule passes, the hook checks Have I Been Pwned (debounced, stale requests cancelled).
+- A "Not found in known data breaches" requirement is `pending` until the check answers, and `isValid` stays `false` until then.
+- A breached password fails with that message and is marked Very Weak. `breach` gives `{ status, count }`, e.g. `{ status: 'pwned', count: 10434004 }`.
+- `<PasswordPolicyInput policyOptions={{ breachCheck: true }} />` shows it in the checklist automatically.
 
-| Variable          | Default    | Description                        |
-| ----------------- | ---------- | ---------------------------------- |
-| `--rpp-accent`    | `#646cff`  | Accent color for focus, buttons.   |
-| `--rpp-success`   | `#27ae60`  | Color for passed requirements.     |
-| `--rpp-danger`    | `#c0392b`  | Color for failed requirements.     |
-| `--rpp-weak`      | `#f39c12`  | Strength meter color for weak.     |
-| `--rpp-medium`    | `#d35400`  | Strength meter color for medium.   |
-| `--rpp-bg`        | `#f9f9f9`  | Component's background color.      |
-| `--rpp-border`    | `#e0e0e0`  | Component's border color.          |
-| `--rpp-text`      | `#333`     | Component's main text color.       |
+On the server, `await validatePasswordAsync(password, policy)` does the same.
 
-### 2. Applying Custom Class Names
+If the service can't be reached, the password is let through by default and `breach.status` is `'error'`. Pass `breachCheck: { failOpen: false }` to block instead. Other settings: `debounceMs` (default 500), `fetch`, `endpoint`, `padding`.
 
-To apply layout styles (like margins or flex properties), simply pass a `className`. This works perfectly with utility-class frameworks like Tailwind CSS.
+For a custom flow, the lower-level `usePwnedPassword(password)` hook and `checkPwnedPassword(password)` (returns the breach count) are still available.
 
-```jsx
-import { PasswordPolicyInput } from 'use-password-policy';
+Only the first 5 characters of the password's SHA-1 hash are sent ([k-anonymity](https://haveibeenpwned.com/API/v3#SearchingPwnedPasswordsByRange)), never the password. It needs `crypto.subtle`, which means HTTPS or `localhost` in browsers and Node 20+ on the server.
+
+### Real strength scoring with zxcvbn
+
+A checklist can't tell `Password1!` apart from a strong password. [zxcvbn](https://github.com/zxcvbn-ts/zxcvbn) can. Add it yourself (it's large, so it isn't bundled) and wrap it with `fromZxcvbn`:
+
+```ts
+import { ZxcvbnFactory } from '@zxcvbn-ts/core';
+import * as common from '@zxcvbn-ts/language-common';
+import * as en from '@zxcvbn-ts/language-en';
+import { fromZxcvbn } from 'use-password-policy';
 
-// Example with Tailwind CSS or a custom utility class
-<PasswordPolicyInput className="mb-4 w-full" />
+const zxcvbn = new ZxcvbnFactory({
+  dictionary: { ...common.dictionary, ...en.dictionary },
+  graphs: common.adjacencyGraphs,
+  translations: en.translations,
+});
+const strengthEstimator = fromZxcvbn(zxcvbn); // create once, outside your component
+
+usePasswordPolicy({ password, strengthEstimator, minStrength: 3 });
 ```
 
-## ❤️ Contributing
+With an estimator, `strengthLabel` and `strengthPercent` come from its score (0–4). `minStrength` adds a "Hard to guess" requirement, and `estimate.feedback` gives you a hint to show the user. `fromZxcvbn` also accepts a plain function, such as the original `zxcvbn` package.
+
+## Form libraries
+
+```ts
+import { z } from 'zod';
+import { zodPasswordRule, passwordValidator } from 'use-password-policy/core';
 
-Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/rahulpatwa1303/use-password-policy/issues).
+// Zod 3 or 4: one issue per failed rule
+const schema = z.object({ password: z.string().superRefine(zodPasswordRule(policy)) });
+
+// react-hook-form: returns true or the first error message
+register('password', { validate: passwordValidator(policy) });
+```
+
+With `breachCheck`, use the async versions, `zodPasswordRuleAsync(policy)` (with `parseAsync`) and `passwordValidatorAsync(policy)`, so the breach check runs too. None of these helpers import Zod or react-hook-form, so they add no dependencies.
+
+## Confirm-password field
+
+```ts
+usePasswordPolicy({ password, confirmPassword });  // adds a "Passwords match" requirement
+```
+
+## Custom messages & i18n
+
+Every requirement has a readable message. You can override any of them with a string or a function:
+
+```ts
+usePasswordPolicy({
+  password,
+  messages: {
+    minLength: (o) => `Mindestens ${o.minLength} Zeichen`,
+    uppercase: 'Ein Großbuchstabe',
+  },
+});
+```
+
+Rule names: `minLength`, `maxLength`, `uppercase`, `lowercase`, `number`, `specialChar`, `notCommon`, `match`, `strength`, plus your custom rule names.
+
+## API
+
+### Options (`PasswordPolicyOptions`)
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `password` | `string` | `''` | Password to check (hook only). |
+| `minLength` | `number` | `8` | Minimum length. `0` turns it off. |
+| `maxLength` | `number` | `0` | Maximum length. `0` means no maximum. |
+| `lowercaseCheck` | `boolean` | `true` | Require a lowercase letter. |
+| `uppercaseCheck` | `boolean` | `true` | Require an uppercase letter. |
+| `numberCheck` | `boolean` | `true` | Require a digit. |
+| `specialCharCheck` | `boolean` | `true` | Require a special character. |
+| `commonPasswordCheck` | `boolean` | `false` | Reject common passwords. |
+| `patternCheck` | `boolean` | `false` | Reject repeats, sequences and keyboard patterns. |
+| `breachCheck` | `boolean \| { failOpen, debounceMs, fetch, endpoint, padding }` | `false` | Include the Have I Been Pwned check (hook and `validatePasswordAsync`). |
+| `commonPasswords` | `string[]` | built-in | Replace the blocklist. |
+| `confirmPassword` | `string` | – | Adds a `match` rule when set. |
+| `strengthEstimator` | `(pw) => { score, feedback? }` | – | For example `fromZxcvbn(zxcvbn)`. |
+| `minStrength` | `0–4` | – | With an estimator: minimum score required. |
+| `customRules` | `PolicyRule[]` | `[]` | `{ name, test, message? }` |
+| `messages` | `Record<string, string \| (o) => string>` | – | Override requirement text. |
+| `lowercaseRegex` / `uppercaseRegex` / `numberRegex` / `specialCharRegex` | `RegExp` | – | Change what counts as each character type. |
+
+### Result (hook and `validatePassword`)
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `isValid` | `boolean` | `true` only when every active rule passes. |
+| `requirements` | `{ name, passed, message }[]` | Ordered checklist, ready to render. |
+| `errors` | `string[]` | Messages of the failed rules. |
+| `policyState` | `Record<string, boolean>` | Pass/fail by rule name. |
+| `strengthLabel` | `'Very Weak' \| 'Weak' \| 'Medium' \| 'Strong' \| 'Very Strong'` | |
+| `strengthPercent` | `number` (0–1) | Fill for a meter. |
+| `strengthScore` | `number` | Number of rules passed. |
+| `estimate` | `{ score, feedback? }` | Only with `strengthEstimator`. |
+| `breach` | `{ status, count }` | Only with `breachCheck`. `status` is `idle`, `checking`, `safe`, `pwned` or `error`. |
+
+Each requirement is `{ name, passed, message, pending? }`. `pending` is `true` while the breach check hasn't answered.
+
+### `<PasswordPolicyInput />` props
+
+It accepts every normal `<input>` prop (`id`, `name`, `placeholder`, `autoComplete`, `onBlur`, and so on) and forwards `ref` to the input. It also takes:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `policyOptions` | `PasswordPolicyOptions` | `{}` | Same options as the hook. |
+| `onPasswordChange` | `(password, validation) => void` | – | Called on every change with the fresh result. |
+| `value` / `defaultValue` | `string` | – | Controlled or uncontrolled. `onChange` works as usual. |
+| `showStrengthMeter` | `boolean` | `true` | |
+| `showStrengthLabel` | `boolean` | `false` | Shows the label ("Strong") under the meter. |
+| `showRequirementsList` | `boolean` | `true` | |
+| `showToggleButton` | `boolean` | `true` | Show/hide password button. |
+| `toggleLabels` | `{ show, hide }` | `Show password` / `Hide password` | Accessible labels for the button. |
+| `className` | `string` | – | Class on the wrapper. |
+| `inputClassName` | `string` | – | Class on the `<input>`. |
+| `unstyled` | `boolean` | `false` | Leaves out the built-in CSS. |
+
+Accessibility: the checklist is linked to the input with `aria-describedby`, the meter has `role="meter"`, `aria-invalid` is set once the user types an invalid password, and each item announces "met" or "not met".
+
+## Styling
+
+The component ships plain CSS with no CSS-in-JS. Theme it with CSS variables from any class:
+
+```css
+.my-password {
+  --rpp-accent: #0ea5e9;
+  --rpp-success: #16a34a;
+  --rpp-danger: #dc2626;
+  --rpp-weak: #ea580c;
+  --rpp-medium: #ca8a04;
+  --rpp-bg: #fff;
+  --rpp-border: #d4d4d8;
+  --rpp-text: #18181b;
+  --rpp-muted: #71717a;
+  --rpp-radius: 8px;
+}
+```
+
+```tsx
+<PasswordPolicyInput className="my-password" />
+```
+
+Each part has a stable class you can target: `.rpp-root`, `.rpp-input`, `.rpp-toggle`, `.rpp-meter`, `.rpp-segment`, `.rpp-requirements`, `.rpp-requirement` (with `[data-passed]`). The built-in selectors have low specificity, so `.my-password .rpp-input { … }` always wins. This works with Tailwind, CSS Modules and styled-components (`styled(PasswordPolicyInput)` still works).
+
+To use your own stylesheet instead of the built-in one, pass `unstyled` and optionally start from the shipped file: `import 'use-password-policy/styles.css'`.
+
+For **Next.js App Router**, the React entry is marked `'use client'`, and `use-password-policy/core` can be used in Server Components and route handlers.
+
+## Upgrading from v2
+
+- **`styled-components` is no longer required.** You can uninstall it if nothing else in your app uses it.
+- The component's DOM and class names changed (`.rpp-*`). The `--rpp-*` theme variables still work.
+- `onPasswordChange` now runs on user changes only, not on mount.
+- The hook's options and return values are backward compatible. New fields were added: `requirements`, `errors`, `strengthPercent`, `estimate`.
+
+See the [CHANGELOG](./CHANGELOG.md).
+
+## Contributing
+
+Issues and PRs are welcome. To get started:
+
+```bash
+npm install
+npm test          # vitest
+npm run build     # tsup
+npm run dev -w demo
+```
 
-## 📄 License
+## License
 
-This project is [MIT](https://github.com/rahulpatwa1303/use-password-policy/blob/main/LICENSE) licensed.
+[MIT](./LICENSE) © Rahul Patwa