{"_id":"@aarongustafson/form-saver","name":"@aarongustafson/form-saver","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@aarongustafson/form-saver","version":"0.0.1","description":"A web component that stores (and restores) values within the form it wraps","keywords":["html","custom element","web component"],"author":{"name":"Aaron Gustafson","email":"aaron@easy-designs.net","url":"https://www.aaron-gustafson.com/"},"license":"MIT","homepage":"https://github.com/aarongustafson/form-saver#readme","repository":{"type":"git","url":"git+https://github.com/aarongustafson/form-saver.git"},"bugs":{"url":"https://github.com/aarongustafson/form-saver/issues"},"type":"module","main":"index.js","module":"form-saver.js","customElements":"custom-elements.json","types":"form-saver.d.ts","exports":{".":{"import":"./index.js"},"./form-saver.js":{"types":"./form-saver.d.ts","import":"./form-saver.js"},"./define.js":{"import":"./define.js"},"./custom-elements.json":"./custom-elements.json"},"engines":{"node":">=20.0.0"},"scripts":{"setup":"node scripts/setup.js","test":"vitest","test:ui":"vitest --ui","test:run":"vitest run","test:coverage":"vitest run --coverage","lint":"npm run lint:eslint && npm run lint:prettier","format":"npm run format:eslint && npm run format:prettier","lint:eslint":"eslint .","format:eslint":"eslint . --fix","lint:prettier":"prettier \"**/*.js\" --check --ignore-path .gitignore","format:prettier":"prettier \"**/*.js\" --write --ignore-path .gitignore","version":"node scripts/update-demo-versions.js && git add demo/esm.html","postversion":"git push --follow-tags"},"devDependencies":{"@open-wc/eslint-config":"^13.0.0","@testing-library/dom":"^10.4.1","@testing-library/user-event":"^14.6.1","@vitest/coverage-v8":"^4.0.10","@vitest/ui":"^4.0.10","eslint":"^9.39.1","eslint-config-prettier":"^10.1.8","happy-dom":"^20.0.10","prettier":"^3.6.2","vitest":"^4.0.10"},"publishConfig":{"access":"public"},"gitHead":"97b063d864e80933b6ef603da86bb939ffbaba2c","_id":"@aarongustafson/form-saver@0.0.1","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-3esbpamvjgjTfpCIrhR5f3zsW0fhBGrDGr5vJIm799OcJOt9q/lDTsvQ996Bx2+CoLlGwjjdgs3OXNVEfkSsIg==","shasum":"c3e4a917cfe7fb7dc374807e236df1948d4c62b5","tarball":"https://registry.npmjs.org/@aarongustafson/form-saver/-/form-saver-0.0.1.tgz","fileCount":8,"unpackedSize":30186,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAN42KkiuBg+iJ0ALz6COzF600CkMqhAcW5JqBi+E4/cAiBHhJ6BtT8M3nzCylKzaPJCHLPpR/zQTnx0chOrP4Dvmg=="}]},"_npmUser":{"name":"aarongustafson","email":"aaron@easy-designs.net"},"directories":{},"maintainers":[{"name":"aarongustafson","email":"aaron@easy-designs.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/form-saver_0.0.1_1776658764668_0.9828889832386201"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-20T04:19:24.577Z","0.0.1":"2026-04-20T04:19:24.851Z","modified":"2026-04-20T04:19:25.051Z"},"maintainers":[{"name":"aarongustafson","email":"aaron@easy-designs.net"}],"description":"A web component that stores (and restores) values within the form it wraps","homepage":"https://github.com/aarongustafson/form-saver#readme","keywords":["html","custom element","web component"],"repository":{"type":"git","url":"git+https://github.com/aarongustafson/form-saver.git"},"author":{"name":"Aaron Gustafson","email":"aaron@easy-designs.net","url":"https://www.aaron-gustafson.com/"},"bugs":{"url":"https://github.com/aarongustafson/form-saver/issues"},"license":"MIT","readme":"# form-saver Web Component\n\n[![npm version](https://img.shields.io/npm/v/@aarongustafson/form-saver.svg)](https://www.npmjs.com/package/@aarongustafson/form-saver) [![Build Status](https://img.shields.io/github/actions/workflow/status/aarongustafson/form-saver/ci.yml?branch=main)](https://github.com/aarongustafson/form-saver/actions)\n\nA web component that stores (and restores) values within the first form it wraps.\n\nIt is designed for crash recovery and interrupted sessions:\n- Saves form field values to `localStorage` as users type.\n- Restores values when the page is loaded again.\n- Clears saved values after a successful submit flow.\n- Optionally retains selected fields after submit.\n\n## Demo\n\n[Live Demo](https://aarongustafson.github.io/form-saver/demo/) ([Source](./demo/index.html))\n\nAdditional demos:\n- [ESM CDN Demo](https://aarongustafson.github.io/form-saver/demo/esm.html) ([Source](./demo/esm.html))\n- [Unpkg CDN Demo](https://aarongustafson.github.io/form-saver/demo/unpkg.html) ([Source](./demo/unpkg.html))\n\n## Installation\n\n```bash\nnpm install @aarongustafson/form-saver\n```\n\n## Usage\n\n### Option 1: Auto-define the custom element (easiest)\n\nImport the package to automatically define the `<form-saver>` custom element:\n\n```javascript\nimport '@aarongustafson/form-saver';\n```\n\nOr use the define-only script in HTML:\n\n```html\n<script src=\"./node_modules/@aarongustafson/form-saver/define.js\" type=\"module\"></script>\n```\n\n### Option 2: Import the class and define manually\n\nImport the class and define the custom element with your preferred tag name:\n\n```javascript\nimport { FormSaverElement } from '@aarongustafson/form-saver/form-saver.js';\n\ncustomElements.define('my-custom-name', FormSaverElement);\n```\n\n### Basic Example\n\n```html\n<form-saver>\n  <form action=\"/contact\" method=\"post\">\n    <label>\n      Name\n      <input name=\"name\" autocomplete=\"name\" />\n    </label>\n    <label>\n      Email\n      <input name=\"email\" type=\"email\" autocomplete=\"email\" />\n    </label>\n    <button type=\"submit\">Send</button>\n  </form>\n</form-saver>\n```\n\nThe component targets the first descendant `<form>`.\n\n### Retain Selected Fields After Submit\n\nUse `retain` to keep specific field names (or ids when `name` is missing) after submit:\n\n```html\n<form-saver retain=\"name email\">\n  <form action=\"/contact\" method=\"post\">\n    <input name=\"name\" />\n    <input name=\"email\" type=\"email\" />\n    <textarea name=\"message\"></textarea>\n    <button type=\"submit\">Send</button>\n  </form>\n</form-saver>\n```\n\nIn this example, `message` is cleared after submit while `name` and `email` remain.\n\n### Let Users Control Retention\n\nTo inject an opt-in checkbox, add `retain-choice`.\n\n```html\n<form-saver\n  retain=\"name email\"\n  retain-choice\n  retain-choice-label=\"Store my contact information for later\"\n>\n  <form action=\"/contact\" method=\"post\">\n    <input name=\"name\" />\n    <input name=\"email\" type=\"email\" />\n    <button type=\"submit\">Send</button>\n  </form>\n</form-saver>\n```\n\nBy default, the checkbox is inserted just before the first submit control.\n\nYou can control placement with `retain-choice-container`, which accepts a CSS selector. The matched element is used as a container — the checkbox is appended inside it:\n\n```html\n<form-saver\n  retain=\"name email\"\n  retain-choice\n  retain-choice-container=\".retain-slot\"\n>\n  <form action=\"/contact\" method=\"post\">\n    <input name=\"name\" />\n    <input name=\"email\" type=\"email\" />\n    <div class=\"retain-slot\"></div>\n    <button type=\"submit\">Send</button>\n  </form>\n</form-saver>\n```\n\n## Attributes\n\n| Attribute | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `retain` | `string` | `\"\"` | Space-separated field names (or ids when name is missing) to retain after successful submit |\n| `retain-choice` | `boolean` | `false` | Inject an opt-in retention checkbox |\n| `retain-choice-label` | `string` | `\"Store my contact information for later\"` | Plain-text label for the injected checkbox |\n| `retain-choice-container` | `string` | `\"\"` | CSS selector for a container element into which the checkbox is appended |\n| `storage-key` | `string` | derived | Optional storage key override |\n\nDefault derived storage key format:\n\n```txt\nform-saver:{method}:{resolvedActionUrl}\n```\n\nWhere `method` and `action` come from the wrapped form.\n\n## Methods\n\n| Method | Description |\n|--------|-------------|\n| `saveFormState()` | Serializes and persists current form values |\n| `restoreFormState()` | Applies saved values to current fields |\n| `clearSavedData()` | Removes saved values for the current form key |\n\n## Field Support\n\nSupported controls include:\n- `input` (except `type=\"file\"`, `submit`, `button`, `reset`, and `image`)\n- `textarea`\n- `select` (single and multiple)\n\nFile fields are intentionally excluded.\n\n## Browser Support\n\nThis component uses modern web standards:\n- Custom Elements v1\n- Light DOM (no shadow root)\n- ES Modules\n\nFor older browsers, you may need polyfills.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n\n# View demo\nopen demo/index.html\n```\n\n## License\n\nMIT © [Aaron Gustafson](https://www.aaron-gustafson.com/)\n","readmeFilename":"README.md","_rev":"1-257d6dfd07173d7a7168982c7dbd2aa3"}