persist-ui/README.md

Universal input persistence for Vanilla, React, Vue, Astro, Next.js etc. with secure AES encryption.

# persist-ui

Universal input persistence for Vanilla, React (including React 19), Vue, Astro, Next.js, Preact, with real AES encryption.

## Installation

```bash
npm install persist-ui crypto-js
```

or via CDN:

```html
<script src="https://unpkg.com/persist-ui"></script>
<script src="https://unpkg.com/crypto-js"></script>
```

## Vanilla JS Usage

```html
<textarea id="textarea-msg"></textarea>
<input type="range" id="slider-level">
<button id="reset">Reset</button>
<button id="submit">Submit</button>
<script type="module">
  import { persistUI } from "persist-ui";
  persistUI.attach(["#textarea-msg", "#slider-level"], {
    key: "feedback",
    resetSelector: "#reset",
    encrypt: true,
    encryptionSecret: "your-strong-secret",
    debounce: 200,
    clearOnSubmit: true,
    submitSelector: "#submit",
    onRestore: data => {
      console.log("Restored:", data);
    }
  });
</script>
```

## React (including React 19)

```typescript
import { usePersistUI } from "persist-ui";
function MyForm() {
  // Works with any form element type (textarea, input, select, etc.)
  const textareaRef = usePersistUI("my-textarea-key", {
    encrypt: true,
    encryptionSecret: "your-strong-secret",
    debounce: 100,
    clearOnSubmit: true,
    submitSelector: "#submit-btn"
  });

  // Works with checkboxes too
  const checkboxRef = usePersistUI("my-checkbox-key", {
    encrypt: true,
    resetOnUnmount: false // Default is false - won't clear on unmount
  });

  return (
    <form>
      <textarea ref={textareaRef} />
      <input type="checkbox" ref={checkboxRef} />
      <button id="submit-btn" type="submit">Submit</button>
    </form>
  );
}
```

## Vue 3

```vue
<script setup>
import { usePersistUI } from "persist-ui";

// Works with any form element type (textarea, input, select, etc.)
const textareaRef = usePersistUI("draft-vue", {
  encrypt: true,
  encryptionSecret: "your-strong-secret",
  debounce: 150,
  clearOnSubmit: true,
  submitSelector: "#submit-btn"
});

// Works with checkboxes too
const checkboxRef = usePersistUI("vue-checkbox", {
  encrypt: true,
  resetOnUnmount: false // Default is false - won't clear on unmount
});
</script>

<template>
  <form>
    <textarea ref="textareaRef" />
    <input type="checkbox" ref="checkboxRef" />
    <button id="submit-btn">Submit</button>
  </form>
</template>
```

## Astro

```astro
---
import { persistUI } from 'persist-ui';
---
<textarea id="astro-feedback"></textarea>
<button id="reset">Reset</button>
<button id="submit">Submit</button>
<script type="module">
  import { persistUI } from 'persist-ui';
  persistUI.attach("#astro-feedback", {
    key: "astro-feedback",
    encrypt: true,
    encryptionSecret: "your-strong-secret",
    resetSelector: "#reset",
    clearOnSubmit: true,
    submitSelector: "#submit"
  });
</script>
```

## Next.js

Identical to the React example, using the hook.

## Options

- `key`: LocalStorage key for persistence.
- `debounce`: Number (ms) to delay saving.
- `encrypt`: Use AES encryption.
- `encryptionSecret`: Secret for AES encryption.
- `ignoreTypes`: Array of input types to ignore (e.g., ["password"]).
- `resetSelector`: Selector for reset button.
- `clearOnSubmit`: Clear storage after submission or redirection.
- `submitSelector`: Selector for submit button.
- `onRestore`: Callback after state is restored.
- `resetOnUnmount`: (React/Vue only) Clear storage when component unmounts.

## Security

- AES encryption with CryptoJS when enabled.
- No use of eval.
- No global exposure.
- Filtered input types.
- Storage is cleared after successful submission or redirection, or when leaving the page if configured.

## License

MIT