{"_id":"@bw-ui/datatable-url-state","_rev":"3-dc76f60f6c2d53a6703483f37846eed3","name":"@bw-ui/datatable-url-state","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@bw-ui/datatable-url-state","version":"1.0.0","keywords":["bw-ui","datatable","plugin","url","state","query-string","history"],"author":{"name":"Black & White UI Engineering"},"license":"MIT","_id":"@bw-ui/datatable-url-state@1.0.0","maintainers":[{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"}],"homepage":"https://bw-ui.dev/bw-datatable","bugs":{"url":"https://github.com/bw-ui/bw-datatable/issues"},"dist":{"shasum":"c7a41a17ea5af773fec4879a3de4122efc367612","tarball":"https://registry.npmjs.org/@bw-ui/datatable-url-state/-/datatable-url-state-1.0.0.tgz","fileCount":4,"integrity":"sha512-6ejJqp7zQvzXCxR86VRvp1LXUC0HG+LOBlYHQnjI53WvoP8o7lulynAY7yvcVNYjqd9FWp9N3PClSNBm8b3ksA==","signatures":[{"sig":"MEUCIQDFRF0x3LULaHqU+qvFyPhA+2IZKpVkmGetluyHc0qwdAIgKf4WnSiM4DEgh1V4ch6vvlfAfB0YN6AiMDh6P2ylgxE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":14858},"main":"dist/url-state.min.js","type":"module","types":"types.d.ts","module":"dist/url-state.esm.min.js","exports":{".":{"import":"./dist/url-state.esm.min.js","require":"./dist/url-state.min.js"}},"scripts":{"dev":"node build.js --watch","build":"node build.js"},"_npmUser":{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"},"repository":{"url":"git+https://github.com/bw-ui/bw-datatable.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.3","description":"URL state sync plugin for @bw-ui/datatable","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.20.0"},"peerDependencies":{"@bw-ui/datatable":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/datatable-url-state_1.0.0_1764604989853_0.054163986885277904","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bw-ui/datatable-url-state","version":"1.0.1","keywords":["bw-ui","datatable","plugin","url","state","query-string","history"],"author":{"name":"Black & White UI Engineering"},"license":"MIT","_id":"@bw-ui/datatable-url-state@1.0.1","maintainers":[{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"}],"homepage":"https://github.com/bw-ui/datatable#readme","bugs":{"url":"https://github.com/bw-ui/datatable/issues"},"dist":{"shasum":"cbe433569ae0e872b4d2d9238e917ceed1389a7d","tarball":"https://registry.npmjs.org/@bw-ui/datatable-url-state/-/datatable-url-state-1.0.1.tgz","fileCount":4,"integrity":"sha512-t/oCTE0aplYTTuJxz4fJ9n6NwnzvCt/QzUaCLrwZq0qqxLf8QvRWYorFrRmnNMaPGgsNV3AeJ6Rd728rAm0Nbw==","signatures":[{"sig":"MEUCIQDDAjiIzz1gCMoRJs0SStoLxqf69Y5HqzRjbRhtbTMY7AIgG6w+0OCwaQ6JzyzP3bVqP2Rc8d8sOiahrHjiq9cryOs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11005},"main":"dist/url-state.min.js","type":"module","types":"src/index.d.ts","module":"dist/url-state.esm.min.js","exports":{".":{"import":"./dist/url-state.esm.min.js","require":"./dist/url-state.min.js"}},"gitHead":"3953ac723b4335e86ba18cd918a31837f2b30d45","scripts":{"dev":"node build.js --watch","build":"node build.js"},"_npmUser":{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"},"repository":{"url":"git+https://github.com/bw-ui/datatable.git","type":"git","directory":"packages/plugins/url-state"},"_npmVersion":"10.9.3","description":"URL state sync plugin for @bw-ui/datatable","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.20.2"},"peerDependencies":{"@bw-ui/datatable":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/datatable-url-state_1.0.1_1764683239954_0.07003839605985362","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bw-ui/datatable-url-state","version":"1.0.2","description":"URL state sync plugin for @bw-ui/datatable","type":"module","main":"dist/url-state.min.js","module":"dist/url-state.esm.min.js","types":"src/index.d.ts","exports":{".":{"import":"./dist/url-state.esm.min.js","require":"./dist/url-state.min.js"}},"scripts":{"build":"node build.js","dev":"node build.js --watch"},"keywords":["bw-ui","datatable","plugin","url","state","query-string","history"],"author":{"name":"Black & White UI Engineering"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bw-ui/bw-datatable.git"},"bugs":{"url":"https://github.com/bw-ui/bw-datatable/issues"},"homepage":"https://bw-ui.github.io/bw-datatable/","peerDependencies":{"@bw-ui/datatable":"^1.0.0"},"devDependencies":{"esbuild":"^0.20.2"},"_id":"@bw-ui/datatable-url-state@1.0.2","gitHead":"47f3eb05ee98558e6e685c6c15091cb227830297","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-7sFvelVnafRD3LArA36AbclWLWFJIrwM3E80pdhQIaqjGNWweuSHPZkkkCMUxyczpkwgPJPNlJ2g7CjB6s+XpQ==","shasum":"ef3f7b9a3c99af03e0f4bb0c2be9f9042a391e50","tarball":"https://registry.npmjs.org/@bw-ui/datatable-url-state/-/datatable-url-state-1.0.2.tgz","fileCount":4,"unpackedSize":11087,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCyqeOza+aPhPjJXzwB/eD3qabC7GzuuNe1tuGo7C0fywIgVOHfM9LrhB/PH5M/zZCYPL8GVl/l7pLSN2BDWGnZZZc="}]},"_npmUser":{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"},"directories":{},"maintainers":[{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/datatable-url-state_1.0.2_1764776947340_0.9743767013159856"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-01T16:03:09.750Z","modified":"2025-12-03T15:49:07.748Z","1.0.0":"2025-12-01T16:03:10.048Z","1.0.1":"2025-12-02T13:47:20.127Z","1.0.2":"2025-12-03T15:49:07.544Z"},"bugs":{"url":"https://github.com/bw-ui/bw-datatable/issues"},"author":{"name":"Black & White UI Engineering"},"license":"MIT","homepage":"https://bw-ui.github.io/bw-datatable/","keywords":["bw-ui","datatable","plugin","url","state","query-string","history"],"repository":{"type":"git","url":"git+https://github.com/bw-ui/bw-datatable.git"},"description":"URL state sync plugin for @bw-ui/datatable","maintainers":[{"name":"rchoudhary.dev","email":"rchoudhary.dev@gmail.com"}],"readme":"# @bw-ui/datatable-url-state\n\nURL state synchronization plugin for BWDataTable.\n\n## Features\n\n- 🔗 **Shareable Links** - Share table state via URL\n- 🔄 **State Persistence** - Sort, filter survive page refresh\n- ⬅️ **Browser History** - Back/forward navigation works\n- ⚙️ **Configurable** - Choose what state to sync\n- 🎯 **Prefix Support** - Multiple tables on same page\n\n## Installation\n\n```bash\nnpm install @bw-ui/datatable-url-state\n```\n\n## Usage\n\n```javascript\nimport { BWDataTable } from '@bw-ui/datatable';\nimport { UrlStatePlugin } from '@bw-ui/datatable-url-state';\n\nconst table = new BWDataTable('#table', { data }).use(UrlStatePlugin, {\n  persist: true, // Save state to URL (default: true)\n  restore: true, // Restore state from URL on load (default: true)\n  prefix: 'dt_', // URL param prefix (default: 'dt_')\n  useHash: false, // Use hash instead of query string (default: false)\n  debounce: 300, // Debounce URL updates (default: 300ms)\n});\n\n// URL automatically updates:\n// - Sort: ?dt_sort=name&dt_dir=asc\n// - Filter: ?dt_filter=john\n// - Page: ?dt_page=2\n```\n\n## Options\n\n| Option      | Type       | Default                      | Description                       |\n| ----------- | ---------- | ---------------------------- | --------------------------------- |\n| `persist`   | `boolean`  | `true`                       | Save state changes to URL         |\n| `restore`   | `boolean`  | `true`                       | Restore state from URL on init    |\n| `prefix`    | `string`   | `'dt_'`                      | Prefix for URL parameters         |\n| `useHash`   | `boolean`  | `false`                      | Use hash (#) instead of query (?) |\n| `debounce`  | `number`   | `300`                        | Debounce delay in milliseconds    |\n| `syncState` | `string[]` | `['sort', 'filter', 'page']` | Which state to sync               |\n\n## URL Parameters\n\nWith default prefix `dt_`:\n\n| Parameter   | Description        | Example          |\n| ----------- | ------------------ | ---------------- |\n| `dt_sort`   | Sort column        | `dt_sort=name`   |\n| `dt_dir`    | Sort direction     | `dt_dir=asc`     |\n| `dt_filter` | Search/filter term | `dt_filter=john` |\n| `dt_page`   | Page number        | `dt_page=2`      |\n\n### Example URLs\n\n```\n# Sorted by name ascending\nhttps://app.com/users?dt_sort=name&dt_dir=asc\n\n# Filtered by \"john\"\nhttps://app.com/users?dt_filter=john\n\n# Combined\nhttps://app.com/users?dt_sort=salary&dt_dir=desc&dt_filter=engineer\n\n# With hash (useHash: true)\nhttps://app.com/users#dt_sort=name&dt_dir=asc\n```\n\n## API\n\n### Methods\n\n```javascript\n// Get shareable URL\nconst url = table.getShareableUrl?.();\n// Returns: \"https://app.com/users?dt_sort=name&dt_dir=asc\"\n\n// Get URL state plugin instance\nconst urlState = table.plugins?.find((p) => p.name === 'url-state');\n\n// Get current state from URL\nconst state = urlState?.getState();\n// Returns: { sortColumn: 'name', sortDirection: 'asc', filter: '' }\n\n// Set state programmatically\nurlState?.setState({ sortColumn: 'email', sortDirection: 'desc' });\n\n// Clear all URL state\nurlState?.clearState();\n```\n\n## Events\n\n```javascript\n// State changed and URL updated\ntable.on('urlstate:change', ({ previous, current, url }) => {\n  console.log('URL state changed:', current);\n  console.log('New URL:', url);\n});\n\n// State restored from URL on init\ntable.on('urlstate:restore', (state) => {\n  console.log('Restored from URL:', state);\n});\n```\n\n## Example: Share Button\n\n```html\n<button id=\"share\">Share Link</button>\n```\n\n```javascript\nconst table = new BWDataTable('#table', { data }).use(UrlStatePlugin);\n\ndocument.getElementById('share').addEventListener('click', async () => {\n  const url = window.location.href;\n\n  try {\n    await navigator.clipboard.writeText(url);\n    alert('Link copied to clipboard!');\n  } catch {\n    prompt('Copy this link:', url);\n  }\n});\n```\n\n## Example: Multiple Tables\n\n```javascript\n// Table 1\nconst table1 = new BWDataTable('#users', { data: users }).use(UrlStatePlugin, {\n  prefix: 'users_',\n});\n\n// Table 2\nconst table2 = new BWDataTable('#orders', { data: orders }).use(\n  UrlStatePlugin,\n  { prefix: 'orders_' }\n);\n\n// URL: ?users_sort=name&orders_sort=date\n```\n\n## Example: Hash-based State\n\nUseful for single-page apps where you can't change query string:\n\n```javascript\nconst table = new BWDataTable('#table', { data }).use(UrlStatePlugin, {\n  useHash: true,\n});\n\n// URL: https://app.com/users#dt_sort=name&dt_dir=asc\n```\n\n## Browser History\n\nThe plugin integrates with browser history:\n\n- **Back button** - Reverts to previous state\n- **Forward button** - Re-applies state\n- **Page refresh** - Restores state from URL\n\n```javascript\n// Listen for browser navigation\nwindow.addEventListener('popstate', () => {\n  // Plugin automatically handles this\n});\n```\n\n## TypeScript\n\n```typescript\nimport { BWDataTable } from '@bw-ui/datatable';\nimport {\n  UrlStatePlugin,\n  UrlStatePluginOptions,\n  UrlState,\n} from '@bw-ui/datatable-url-state';\n\nconst options: UrlStatePluginOptions = {\n  persist: true,\n  restore: true,\n  prefix: 'tbl_',\n  syncState: ['sort', 'filter'],\n};\n\nconst table = new BWDataTable('#table', { data }).use(UrlStatePlugin, options);\n\ntable.on('urlstate:change', ({ current }: { current: UrlState }) => {\n  console.log('Sort:', current.sortColumn, current.sortDirection);\n});\n```\n\n## Notes\n\n- URL updates are debounced to prevent excessive history entries\n- State is restored after table initialization\n- Works with both hash and query string modes\n- Handles URL encoding/decoding automatically\n\n## License\n\nMIT © [BW UI](https://github.com/AshwinPavanKadha/bw-ui)\n","readmeFilename":"README.md"}