{"_id":"@academix-admin/overlay-route","name":"@academix-admin/overlay-route","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@academix-admin/overlay-route","version":"0.1.0","description":"Give a sheet, picker or dialog its own history entry, so the platform's back gesture closes the overlay rather than the page under it.","keywords":["react","overlay","sheet","history","back-button","back-gesture","url-fragment"],"license":"MIT","author":{"name":"Academix"},"repository":{"type":"git","url":"git+https://github.com/academix-admin/academix-ui.git","directory":"packages/overlay-route"},"homepage":"https://github.com/academix-admin/academix-ui/tree/main/packages/overlay-route#readme","bugs":{"url":"https://github.com/academix-admin/academix-ui/issues"},"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"scripts":{"build":"tsup","clean":"rimraf dist","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0"},"devDependencies":{"@testing-library/react":"^16.1.0","@types/react":"^19.0.0","@types/react-dom":"^19.0.0","jsdom":"^25.0.1","react":"^18.3.1","react-dom":"^18.3.1","rimraf":"^6.0.1","tsup":"^8.3.5","typescript":"^5.9.3","vitest":"^2.1.8"},"publishConfig":{"access":"public"},"gitHead":"2b88aaf23c732b09086c873f38898446da1d47bb","_id":"@academix-admin/overlay-route@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-bYLZhoO8aZe5bT9wp8nUeV0G5HTrjaAzkHtwySPWf1zp7L3ot/n/1YNKLUzPYIJAqdHlYguZIazuVbGjYDC9bg==","shasum":"664ac6fec4c981f0167fdaba8f4dff2010c0a0ab","tarball":"https://registry.npmjs.org/@academix-admin/overlay-route/-/overlay-route-0.1.0.tgz","fileCount":9,"unpackedSize":92423,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDAGY7ZOK52rY0LWE98IqnlFG250X5Ik7Txi9gPF2y4qQIhAJQVTOkspfu6tVjW/ngNpXTcv4E5k2LEqOycAypaYsgh"}]},"_npmUser":{"name":"academix-group","email":"academix.tech4u@gmail.com"},"directories":{},"maintainers":[{"name":"academix-group","email":"academix.tech4u@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/overlay-route_0.1.0_1788356469076_0.4926698152863369"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T13:41:08.777Z","0.1.0":"2026-09-02T13:41:09.187Z","modified":"2026-09-02T13:41:09.513Z"},"maintainers":[{"name":"academix-group","email":"academix.tech4u@gmail.com"}],"description":"Give a sheet, picker or dialog its own history entry, so the platform's back gesture closes the overlay rather than the page under it.","homepage":"https://github.com/academix-admin/academix-ui/tree/main/packages/overlay-route#readme","keywords":["react","overlay","sheet","history","back-button","back-gesture","url-fragment"],"repository":{"type":"git","url":"git+https://github.com/academix-admin/academix-ui.git","directory":"packages/overlay-route"},"author":{"name":"Academix"},"bugs":{"url":"https://github.com/academix-admin/academix-ui/issues"},"license":"MIT","readme":"# @academix-admin/overlay-route\n\nGive a sheet, picker or dialog its own history entry, so the platform's own **Back** closes the\noverlay rather than the page under it.\n\nWithout one, Back with a picker open closes the picker *and* leaves the page behind it. Measured in\na real shop: the back gesture walked straight out of a half-built sale.\n\n```tsx\nimport { useOverlayRoute } from '@academix-admin/overlay-route';\n\nconst [open, setOpen] = useState(false);\nuseOverlayRoute('cart:picker', open, () => setOpen(false));\n```\n\nThat is the whole API for most consumers. The name must be unique among overlays that can be open\nat the same time, or they mistake each other's entry.\n\n## Surviving a reload\n\nThe fragment outlives a refresh, so an app can come back with `#ax=…` naming a sheet. Pass\n`onRestore` and the overlay reopens exactly where it was left:\n\n```tsx\nuseOverlayRoute('cart:picker', open, () => setOpen(false), {\n  onRestore: () => setOpen(true),\n});\n```\n\nThis needs a name that is **stable across loads**: `'cart:picker'` restores, `` `picker:${useId()}` ``\ncannot, because the id is new every time.\n\nAn overlay that does not restore is closed for you. A URL naming a sheet nobody is showing costs a\nwhole Back press — the user pressing it twice to leave one page, which is exactly how a web app\nstops feeling like a real one.\n\n## Working alongside a navigation library\n\nAn overlay's entry is a real history entry, and a navigation library that pops pages with\n`history.go(-n)` has to count it: `go` counts positions in the browser's single global list, so an\nentry it does not know about leaves every later pop short by one.\n\nNeither package should have to know the other exists. They meet at one function:\n\n```ts\nimport { setHistoryWriter } from '@academix-admin/overlay-route';\n\nsetHistoryWriter(({ mode, href, state }) => {\n  // write it, and record it in your own ledger\n});\n```\n\n`@academix-admin/navigation-stack` does this on import — no wiring, no provider. Nothing registers?\nThe default writer is used and everything here still works; there is simply no ledger to join.\n\n## What it does to the URL\n\nState lives in the URL **fragment**, because a fragment write never reaches the server, so opening a\nsheet cannot trigger a server render. The fragment is not ours, though — `#section-3` deep links and\n`scrollIntoView` anchors are ordinary site behaviour — so this owns exactly one `&`-separated `ax=`\nsegment and passes every other one through untouched, in its original order.\n\n## API\n\n| | |\n|---|---|\n| `useOverlayRoute(name, open, onClose, opts?)` | The hook. `opts.onRestore` reopens after a reload. |\n| `readOverlayFragment()` | The overlay named in the URL now, or `null`. |\n| `writeOverlayFragment(name, mode)` | Write the segment directly. |\n| `closeUnrestoredOverlay()` | Close one the URL names but nothing showed. |\n| `settleOverlayFragment()` | Schedule that, once, after the first frames. |\n| `claimOverlay` / `releaseOverlay` / `isOverlayClaimed` / `overlayClaims` | Say what is on screen. |\n| `setHistoryWriter(fn)` | Hand history writing to a navigation library. |\n| `parseFragment` / `buildFragment` / `setInFragment` | The pure codec. |\n","readmeFilename":"README.md","_rev":"1-a27629fc357ec1858874a19d002804bd"}