@dojo-ng/history 0.1.0 → 0.2.0

package/README.md

@@ -69,7 +69,8 @@ nothing else, so Back never adds an entry.
 - `canGoBack`, `canGoForward`: properties. The browser does not say whether Back or Forward has
   somewhere to go, so each entry carries a private `{ id, index }` in `history.state`, and the
   highest index is kept in `sessionStorage`. Without `sessionStorage`, `canGoForward` is `false`.
-- `href(path)`: `base` plus `path`, for a link's `href`
+- `href(path)`: `base` plus `path`, for a link's `href` (`#` plus `path` in hash mode)
+- `block(blocker)`: ask before a move; returns a function that removes the blocker. See Guards.
 - `annotate({ state?, trail? })`: replace those fields on the current entry (with `replaceState`)
   and publish the location again. It sets whichever of the two you pass; it does not merge inside `state`.
 - `commit()`: commit the current entry now
@@ -81,6 +82,9 @@ nothing else, so Back never adds an entry.
 |---|---|---|
 | `base` | `""` | A path prefix such as `/acme`. Added to every URL written and stripped from every path read. |
 | `dwellMs` | `3000` | Visible milliseconds before an entry commits. `0` gives plain browser behavior. |
+| `mode` | `"path"` | `"hash"` keeps the route after `#`. See Hash mode. |
+| `scroll` | `false` | `true` or `{ targets?, ready? }`: restore scroll on Back, Forward and reload. See Scroll restoration. |
+| `focus` | `false` | A selector to focus after a `go`. See Focus after a navigation. |
 | `onCommit` | none | Called once for each entry that commits. See Hooks. |
 | `resolve` | none | Rebuilds the state of a landing entry that has none. See Hooks. |
 | `window` | `globalThis.window` | For tests: any object shaped like the parts of `window` this uses. |
@@ -112,6 +116,94 @@ result becomes the entry's state. If it rejects, the error is logged and the bar
 published. A reload in the same tab keeps its state, so `resolve` is not called. If the app
 navigates before `resolve` settles, the late result is dropped.
 
+## Hash mode
+
+```js
+installHistory(bus, { mode: "hash" });   // https://example.com/app.html#/orders/7
+```
+
+The route lives after the `#`, so a static server with no fallback can serve every deep link: a
+reload on `#/orders/7` just loads `app.html`. Everything else works as in path mode. `go` writes
+`#/orders/7`, `href("/orders/7")` returns `#/orders/7`, and `location.path` is still `/orders/7`.
+
+- A user editing the hash in the address bar, or clicking a plain `<a href="#/x">`, is published as
+  a `go` and stamped like any other entry. Nothing in your app has to listen for `hashchange`.
+- Hash mode owns the whole hash, so an in-page `#section` link can't also scroll to a section. Use
+  `element.scrollIntoView()` for that.
+- `base` is ignored, with one `console.warn`, because the page's own path is fixed.
+- Components build their links with `getHistory().href(path)`, so hash mode needs `installHistory`
+  to have run. Without it a component falls back to its plain `href`.
+- Blockers (see Guards) are not asked about an address-bar hash edit: the browser has already
+  moved, and it can't be put back safely.
+
+## Scroll restoration
+
+```js
+installHistory(bus, { scroll: true });
+installHistory(bus, {
+  scroll: {
+    targets: () => [document.getElementById("list")],      // scrolling elements; each needs an id
+    ready: (location) => view.updateComplete,               // resolve when the view has rendered
+  },
+});
+```
+
+Off by default, because turning it on sets `history.scrollRestoration` to `"manual"` (put back by
+`destroy()`), which an app should choose.
+
+- Back, Forward and a same-tab reload return the window, and each `targets` element, to where the
+  user left that entry. A `go` scrolls to the top, or to the element named by a `#fragment` in the
+  path (path mode only).
+- Positions are saved when leaving an entry and on `pagehide`. They are kept in `sessionStorage`
+  by entry id, newest 50, never in `history.state`. Without `sessionStorage`, nothing is restored.
+- A skimmed entry that gets replaced (see Dwell) loses its saved position.
+- **`ready` is the contract.** History publishes the location and does not render, so it can't know
+  when the view is there. Without `ready`, it waits two animation frames, which is right for a view
+  that renders at once and not enough for data that loads later. With a Lit view, `ready` can
+  return `view.updateComplete`; with fetched data, a promise for the fetch. A `ready` that rejects
+  is logged and the scroll still happens.
+
+## Focus after a navigation
+
+```js
+installHistory(bus, { focus: "h1, [role=main], main" });
+```
+
+After a `go`, once the view has had its frames (or `scroll.ready`), the first element matching the
+selector gets focus, so keyboard and screen reader users learn the page changed. Without this,
+focus stays on the link that was clicked, which may no longer exist. Most apps will want it on.
+
+- An element that can't take focus, such as a heading, gets `tabindex="-1"` until it blurs.
+- Focus does not move on Back, Forward or a reload. The browser's own behavior is right there.
+- Focus already inside the matched element is left alone, so choosing a tree node keeps focus on
+  the tree.
+
+## Guards
+
+```js
+const unblock = history.block((to, from) => !formIsDirty() || confirm("Leave without saving?"));
+// later, after saving:
+unblock();
+```
+
+`block` runs the blocker before every `go` and every Back or Forward. Return `true` to allow the
+move; the function may be async. With several blockers, all must allow. Anything other than `true`
+(or a throw) refuses.
+
+- A refused `go` writes nothing, publishes nothing and leaves the dwell state alone. If a second
+  `go` arrives while a check is pending, only the latest is checked.
+- A browser can't cancel a Back, only undo it. So a guarded Back is traversed straight back with
+  `history.go`, the blocker is asked, and if it allows the move the traversal is replayed and
+  published as usual. No `pushState` or `replaceState` is involved. Entries this package did not
+  create are not guarded.
+- While any blocker is active, closing or reloading the tab shows the browser's own prompt. Browsers
+  ignore custom text there.
+- `to` is the `nav:go` payload, or `{ path, source: "pop" }` for Back and Forward. `from` is the
+  current location.
+- `dj-back-button`'s cancelable `dj-back` event runs first; the two compose.
+- The Navigation API could later give a true cancel in place of the undo and replay, where it is
+  available. It isn't used here, so older Safari works.
+
 ## match
 
 ```js

package/dist/handle.d.ts

@@ -45,6 +45,13 @@ export interface CommitEntry {
     state: unknown;
     trail?: TrailEntry[];
 }
+/** What a blocker is asked about: a `nav:go`, or a Back/Forward (`source: "pop"`) to `path`. */
+export type BlockTarget = NavGo | {
+    path: string;
+    source: "pop";
+};
+/** Return true to allow the move. May be async. See `HistoryInstance.block`. */
+export type Blocker = (to: BlockTarget, from: NavLocation) => boolean | Promise<boolean>;
 export interface HistoryInstance {
     /** Publish `nav:go`. The only way anything here writes to the browser's history. */
     go(path: string, state?: unknown, options?: GoOptions): void;
@@ -58,7 +65,13 @@ export interface HistoryInstance {
     readonly current: NavLocation | undefined;
     readonly canGoBack: boolean;
     readonly canGoForward: boolean;
-    /** The URL for an app path: `base` plus `path`. */
+    /**
+     * Ask before a move. `blocker` runs for every `nav:go` and every Back/Forward; all active blockers
+     * must return true. A refused move writes and publishes nothing. Returns a function that removes the
+     * blocker. While any blocker is active, closing the tab shows the browser's own prompt.
+     */
+    block(blocker: Blocker): () => void;
+    /** The URL for an app path: `base` plus `path`. In `mode: "hash"`, `#` plus `path`. */
     href(path: string): string;
     /** Merge `state` and/or `trail` into the current entry, then publish the location again. */
     annotate(partial: NavAnnotation): void;

package/dist/history.d.ts

@@ -1,5 +1,5 @@
 import type { PubSub } from "@dojo-ng/pubsub";
-import { type CommitEntry, type HistoryInstance } from "./handle.js";
+import { type CommitEntry, type HistoryInstance, type NavLocation } from "./handle.js";
 /** The parts of `window` that `installHistory` uses. Tests pass a fake with this shape. */
 export interface HistoryWindow {
     history: {
@@ -7,6 +7,8 @@ export interface HistoryWindow {
         replaceState(state: unknown, title: string, url?: string | null): void;
         back(): void;
         forward(): void;
+        go(delta: number): void;
+        scrollRestoration?: "auto" | "manual";
         readonly state: unknown;
     };
     location: {
@@ -15,10 +17,17 @@ export interface HistoryWindow {
         readonly hash: string;
         readonly href: string;
     };
+    readonly scrollX?: number;
+    readonly scrollY?: number;
+    scrollTo?(x: number, y: number): void;
+    requestAnimationFrame?(callback: () => void): unknown;
     addEventListener(type: string, listener: (event: never) => void): void;
     removeEventListener(type: string, listener: (event: never) => void): void;
     document: {
         readonly visibilityState?: string;
+        readonly activeElement?: Element | null;
+        getElementById?(id: string): Element | null;
+        querySelector?(selector: string): Element | null;
         addEventListener(type: string, listener: (event: never) => void): void;
         removeEventListener(type: string, listener: (event: never) => void): void;
     };
@@ -27,6 +36,16 @@ export interface HistoryWindow {
         setItem(key: string, value: string): void;
     };
 }
+/** What `scroll` takes beyond `true`. */
+export interface ScrollOptions {
+    /** Scrollable elements besides the window. Each needs an `id`; one without is skipped, with a warning. */
+    targets?: () => Iterable<Element>;
+    /**
+     * Resolve when the view for `location` has rendered. Without it, restoring waits two animation
+     * frames, which is right for a synchronous render and not enough for data that loads later.
+     */
+    ready?: (location: NavLocation) => Promise<void> | void;
+}
 export interface InstallOptions {
     /** A path prefix such as `/acme`. Added to every URL written, stripped from every path read. */
     base?: string;
@@ -41,5 +60,23 @@ export interface InstallOptions {
      * bookmark). Its result becomes the entry's state before `nav:location` is published as `load`.
      */
     resolve?: (path: string) => Promise<unknown>;
+    /**
+     * `"hash"` keeps the route after `#` (`#/orders/7`), so a server with no SPA fallback can serve any
+     * deep link. Default `"path"`. Hash mode owns the whole hash, so in-page `#anchor` links don't work
+     * there, and `base` is ignored.
+     */
+    mode?: "path" | "hash";
+    /**
+     * Restore the scroll position on Back, Forward and reload, and scroll to the top (or to a
+     * `#fragment`) after a `go`. Off by default. Turning it on sets `history.scrollRestoration` to
+     * `"manual"` until `destroy()`.
+     */
+    scroll?: boolean | ScrollOptions;
+    /**
+     * A selector. After a `go` (not a Back or a reload), focus the first match so keyboard and screen
+     * reader users learn the view changed. An element that can't take focus gets `tabindex="-1"` until
+     * it blurs. Focus already inside the match is left alone. Default off.
+     */
+    focus?: string | false;
 }
 export declare function installHistory(bus: PubSub, options?: InstallOptions): HistoryInstance;

package/dist/history.js

@@ -1,6 +1,9 @@
 import { getHistory, registerHistory, unregisterHistory, } from "./handle.js";
 const DEFAULT_DWELL_MS = 3000;
 const MAX_INDEX_KEY = "dojo-ng.history.max";
+const SCROLL_KEY = "dojo-ng.history.scroll";
+const SCROLL_CAP = 50;
+const FOCUSABLE = "a[href], area[href], button, input, select, textarea, summary, iframe, [tabindex], [contenteditable]";
 const DUPLICATE_INSTALL_WARNED = new WeakSet();
 let idCounter = 0;
 function newId() {
@@ -43,9 +46,20 @@ export function installHistory(bus, options = {}) {
     const win = options.window ?? globalThis.window;
     if (!win)
         throw new Error("[@dojo-ng/history] installHistory needs a window. Pass options.window outside a browser.");
-    const base = normalizeBase(options.base);
+    const hashMode = options.mode === "hash";
+    const base = hashMode ? "" : normalizeBase(options.base);
     const dwellMs = options.dwellMs ?? DEFAULT_DWELL_MS;
+    const scrollOn = Boolean(options.scroll);
+    const scrollOpts = typeof options.scroll === "object" ? options.scroll : {};
+    const focusSelector = options.focus || undefined;
+    const blockers = new Set();
     const warned = new Set();
+    let guardToken = 0;
+    let undoing;
+    let redoing = false;
+    let pendingAdopt = false;
+    let settleToken = 0;
+    let savedRestoration;
     const provisionalIds = new Set();
     let cur;
     let last;
@@ -62,6 +76,10 @@ export function installHistory(bus, options = {}) {
         console.warn(`[@dojo-ng/history] ${message} (${signal}). Dojo NG routing stays in charge; this is the only warning of this kind.`);
     }
     function currentPath() {
+        if (hashMode) {
+            const route = win.location.hash.replace(/^#/, "");
+            return route === "" ? "/" : route.startsWith("/") ? route : `/${route}`;
+        }
         const full = win.location.pathname + win.location.search + win.location.hash;
         if (base && (full === base || full.startsWith(`${base}/`) || full.startsWith(`${base}?`) || full.startsWith(`${base}#`))) {
             const rest = full.slice(base.length);
@@ -70,7 +88,10 @@ export function installHistory(bus, options = {}) {
         return full;
     }
     function place() {
-        return win.location.pathname + win.location.search;
+        return win.location.pathname + win.location.search + (hashMode ? win.location.hash : "");
+    }
+    function hrefOf(path) {
+        return hashMode ? `#${path}` : base + path;
     }
     function stateFor(entry) {
         return { __djnav: { id: entry.id, index: entry.index }, state: entry.state, trail: entry.trail };
@@ -114,15 +135,18 @@ export function installHistory(bus, options = {}) {
             // Storage can be blocked. canGoForward is then false, which is harmless.
         }
     }
-    function publish() {
-        const location = {
-            path: cur.path,
-            state: cur.state,
-            index: cur.index,
-            committed: cur.committed,
-            source: cur.source,
-            ...(cur.trail ? { trail: cur.trail } : {}),
+    function toLocation(entry) {
+        return {
+            path: entry.path,
+            state: entry.state,
+            index: entry.index,
+            committed: entry.committed,
+            source: entry.source,
+            ...(entry.trail ? { trail: entry.trail } : {}),
         };
+    }
+    function publish() {
+        const location = toLocation(cur);
         last = location;
         bus.publish("nav:location", location);
     }
@@ -181,6 +205,162 @@ export function installHistory(bus, options = {}) {
         publish();
         fireCommit(cur);
     }
+    // --- scroll and focus ----------------------------------------------------------------------
+    // Positions live in sessionStorage by entry id, never in history state: writing them into state
+    // would need a replaceState from a scroll or pop handler, and only nav:go may write.
+    function readScrollStore() {
+        try {
+            const raw = win.sessionStorage?.getItem(SCROLL_KEY);
+            const parsed = raw ? JSON.parse(raw) : undefined;
+            if (parsed && Array.isArray(parsed.order) && isRecord(parsed.pos))
+                return parsed;
+        }
+        catch {
+            // Blocked storage or a damaged value: start empty.
+        }
+        return { order: [], pos: {} };
+    }
+    function writeScrollStore(store) {
+        try {
+            win.sessionStorage?.setItem(SCROLL_KEY, JSON.stringify(store));
+        }
+        catch {
+            // Storage can be blocked. Restoring is then a no-op.
+        }
+    }
+    function saveScroll(id) {
+        if (!scrollOn)
+            return;
+        const record = { x: win.scrollX ?? 0, y: win.scrollY ?? 0 };
+        if (scrollOpts.targets) {
+            for (const el of scrollOpts.targets()) {
+                if (!el.id) {
+                    warnOnce("scroll-target-id", "A scroll target has no id, so its position can't be saved");
+                    continue;
+                }
+                (record.t ?? (record.t = {}))[el.id] = [el.scrollLeft, el.scrollTop];
+            }
+        }
+        const store = readScrollStore();
+        if (!(id in store.pos))
+            store.order.push(id);
+        store.pos[id] = record;
+        while (store.order.length > SCROLL_CAP)
+            delete store.pos[store.order.shift()];
+        writeScrollStore(store);
+    }
+    function dropScroll(id) {
+        if (!scrollOn)
+            return;
+        const store = readScrollStore();
+        if (!(id in store.pos))
+            return;
+        delete store.pos[id];
+        store.order = store.order.filter((other) => other !== id);
+        writeScrollStore(store);
+    }
+    function restoreScroll(id) {
+        const record = readScrollStore().pos[id];
+        if (!record)
+            return;
+        win.scrollTo?.(record.x, record.y);
+        if (!scrollOpts.targets || !record.t)
+            return;
+        for (const el of scrollOpts.targets()) {
+            const at = el.id ? record.t[el.id] : undefined;
+            if (at) {
+                el.scrollLeft = at[0];
+                el.scrollTop = at[1];
+            }
+        }
+    }
+    function scrollForGo(path) {
+        const hash = path.indexOf("#");
+        let target;
+        if (!hashMode && hash >= 0) {
+            try {
+                target = win.document.getElementById?.(decodeURIComponent(path.slice(hash + 1)));
+            }
+            catch {
+                target = undefined;
+            }
+        }
+        if (target)
+            target.scrollIntoView();
+        else
+            win.scrollTo?.(0, 0);
+    }
+    function moveFocus() {
+        const target = win.document.querySelector?.(focusSelector);
+        if (!target)
+            return;
+        const active = win.document.activeElement;
+        if (active && target.contains(active))
+            return;
+        if (!target.matches(FOCUSABLE)) {
+            target.setAttribute("tabindex", "-1");
+            target.addEventListener("blur", () => target.removeAttribute("tabindex"), { once: true });
+        }
+        target.focus({ preventScroll: scrollOn });
+    }
+    /** The view renders after the publish, and history can't see it (D4), so wait for the app's word or two frames. */
+    function whenRendered(location) {
+        if (scrollOpts.ready) {
+            return new Promise((resolve) => resolve(scrollOpts.ready(location))).catch((err) => {
+                console.error("[@dojo-ng/history] scroll.ready rejected; restoring anyway:", err);
+            });
+        }
+        const frame = win.requestAnimationFrame?.bind(win);
+        if (!frame)
+            return Promise.resolve();
+        return new Promise((resolve) => frame(() => frame(() => resolve())));
+    }
+    /** Called after a published location. A newer navigation cancels the wait of an older one. */
+    function afterNavigation(entry) {
+        if (!scrollOn && !focusSelector)
+            return;
+        const token = ++settleToken;
+        const isGo = entry.source === "go";
+        const path = entry.path;
+        void whenRendered(toLocation(entry)).then(() => {
+            if (destroyed || token !== settleToken)
+                return;
+            if (scrollOn) {
+                if (isGo)
+                    scrollForGo(path);
+                else
+                    restoreScroll(entry.id);
+            }
+            if (focusSelector && isGo)
+                moveFocus();
+        });
+    }
+    function onPageHide() {
+        if (!destroyed)
+            saveScroll(cur.id);
+    }
+    // --- guards --------------------------------------------------------------------------------
+    async function allows(to) {
+        const from = last ?? toLocation(cur);
+        try {
+            const answers = await Promise.all([...blockers].map(({ fn }) => fn(to, from)));
+            return answers.every((answer) => answer === true);
+        }
+        catch (err) {
+            console.error("[@dojo-ng/history] a blocker threw; the move is refused:", err);
+            return false;
+        }
+    }
+    function onBeforeUnload(event) {
+        event.preventDefault();
+    }
+    async function runUndone(pending) {
+        const ok = await allows(pending.to);
+        if (!ok || destroyed || pending.token !== guardToken)
+            return;
+        redoing = true;
+        win.history.go(pending.delta);
+    }
     // --- the coexistence checks (D6) -----------------------------------------------------------
     function checkForeignLocation() {
         if (place() !== expectedPlace) {
@@ -191,9 +371,34 @@ export function installHistory(bus, options = {}) {
     function onGo(request) {
         if (destroyed || !request || typeof request.path !== "string")
             return;
-        checkForeignLocation();
+        if (pendingAdopt) {
+            // An address-bar hash edit the browser already made. A blocker can't undo it safely, so it isn't asked.
+            pendingAdopt = false;
+            performGo(request, true);
+        }
+        else if (blockers.size === 0) {
+            performGo(request, false);
+        }
+        else {
+            // Last one wins: a newer request, or any pop, makes this answer stale.
+            const token = ++guardToken;
+            void allows(request).then((ok) => {
+                if (ok && !destroyed && token === guardToken)
+                    performGo(request, false);
+            });
+        }
+    }
+    /** `adopt`: the browser has already pushed this entry (unstamped), so stamp it in place as the next index. */
+    function performGo(request, adopt) {
+        guardToken++;
+        if (!adopt)
+            checkForeignLocation();
         const previous = cur;
-        const replace = request.replace === true || !previous.committed;
+        const replace = !adopt && (request.replace === true || !previous.committed);
+        if (replace)
+            dropScroll(previous.id);
+        else
+            saveScroll(previous.id);
         const entry = {
             id: newId(),
             index: replace ? previous.index : previous.index + 1,
@@ -205,14 +410,14 @@ export function installHistory(bus, options = {}) {
         };
         provisionalIds.delete(previous.id);
         stopTimer();
-        writeEntry(replace ? "replace" : "push", entry, base + request.path);
+        writeEntry(replace || adopt ? "replace" : "push", entry, hrefOf(request.path));
         if (!replace)
             writeMax(entry.index);
         expectedPlace = place();
         cur = entry;
         // A replace of an entry that had already committed keeps its place on the stack, so the
         // replacement commits too. Otherwise the entry is provisional until it has been read.
-        const commitNow = dwellMs <= 0 || (replace && previous.committed);
+        const commitNow = dwellMs <= 0 || adopt || (replace && previous.committed);
         if (commitNow) {
             entry.committed = true;
             publish();
@@ -223,13 +428,43 @@ export function installHistory(bus, options = {}) {
             publish();
             startDwell();
         }
+        afterNavigation(entry);
     }
     function onPop() {
         if (destroyed)
             return;
-        stopTimer();
+        if (undoing) {
+            // The traversal we made to put a guarded Back back. Nothing changed; ask the blockers.
+            const pending = undoing;
+            undoing = undefined;
+            void runUndone(pending);
+            return;
+        }
+        if (redoing) {
+            redoing = false;
+            settlePop();
+            return;
+        }
+        if (blockers.size > 0) {
+            const target = readStamp(win.history.state);
+            if (target && target.id !== cur.id && target.index !== cur.index) {
+                const delta = target.index - cur.index;
+                undoing = { delta, token: ++guardToken, to: { path: currentPath(), source: "pop" } };
+                win.history.go(-delta);
+                return;
+            }
+        }
+        settlePop();
+    }
+    function settlePop() {
+        guardToken++;
         const raw = win.history.state;
         const stamp = readStamp(raw);
+        // Hash mode: an unstamped entry here is an address-bar edit. The hashchange that follows adopts it.
+        if (hashMode && !stamp && place() !== expectedPlace)
+            return;
+        stopTimer();
+        saveScroll(cur.id);
         let entry;
         let newlyCommitted = false;
         if (!stamp) {
@@ -262,6 +497,14 @@ export function installHistory(bus, options = {}) {
         publish();
         if (newlyCommitted)
             fireCommit(entry);
+        afterNavigation(entry);
+    }
+    function onHashChange() {
+        if (destroyed || readStamp(win.history.state))
+            return;
+        pendingAdopt = true;
+        bus.publish("nav:go", { path: currentPath(), replace: true });
+        pendingAdopt = false;
     }
     function onNavigate(event) {
         const detail = event.detail;
@@ -299,9 +542,18 @@ export function installHistory(bus, options = {}) {
             const max = readMax();
             return max !== undefined && cur.index < max;
         },
-        href(path) {
-            return base + path;
+        block(blocker) {
+            const entry = { fn: blocker };
+            blockers.add(entry);
+            if (blockers.size === 1)
+                win.addEventListener("beforeunload", onBeforeUnload);
+            return () => {
+                if (!blockers.delete(entry) || blockers.size > 0)
+                    return;
+                win.removeEventListener("beforeunload", onBeforeUnload);
+            };
         },
+        href: hrefOf,
         annotate(partial) {
             if (destroyed)
                 return;
@@ -319,6 +571,13 @@ export function installHistory(bus, options = {}) {
             stopTimer();
             unsubscribeGo();
             win.removeEventListener("popstate", onPop);
+            win.removeEventListener("hashchange", onHashChange);
+            win.removeEventListener("pagehide", onPageHide);
+            if (blockers.size > 0)
+                win.removeEventListener("beforeunload", onBeforeUnload);
+            blockers.clear();
+            if (savedRestoration !== undefined)
+                win.history.scrollRestoration = savedRestoration;
             win.document.removeEventListener("visibilitychange", onVisibility);
             win.document.removeEventListener("dj-navigate", onNavigate);
             unregisterHistory(instance);
@@ -328,6 +587,12 @@ export function installHistory(bus, options = {}) {
     if (!isNative(win.history.pushState) || !isNative(win.history.replaceState)) {
         warnOnce("patched-pushstate", "history.pushState or replaceState is not the browser's own, so another router may be patching them");
     }
+    if (hashMode && options.base)
+        warnOnce("hash-base", "`base` is ignored in hash mode, because the route lives after the #");
+    if (scrollOn && win.history.scrollRestoration !== undefined) {
+        savedRestoration = win.history.scrollRestoration;
+        win.history.scrollRestoration = "manual";
+    }
     const raw = win.history.state;
     const stamp = readStamp(raw);
     let fresh = false;
@@ -344,6 +609,10 @@ export function installHistory(bus, options = {}) {
     expectedPlace = place();
     const unsubscribeGo = bus.subscribe("nav:go", onGo, { replay: false });
     win.addEventListener("popstate", onPop);
+    if (hashMode)
+        win.addEventListener("hashchange", onHashChange);
+    if (scrollOn)
+        win.addEventListener("pagehide", onPageHide);
     win.document.addEventListener("visibilitychange", onVisibility);
     win.document.addEventListener("dj-navigate", onNavigate);
     registerHistory(instance);
@@ -366,6 +635,8 @@ export function installHistory(bus, options = {}) {
     }
     else {
         publish();
+        if (!fresh)
+            afterNavigation(cur);
     }
     return instance;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { installHistory } from "./history.js";
-export type { InstallOptions, HistoryWindow } from "./history.js";
+export type { InstallOptions, HistoryWindow, ScrollOptions } from "./history.js";
 export { match } from "./match.js";
 export { getHistory, whenHistory } from "./handle.js";
-export type { CommitEntry, GoOptions, HistoryInstance, NavAnnotation, NavGo, NavigateDetail, NavLocation, NavSource, TrailEntry, } from "./handle.js";
+export type { Blocker, BlockTarget, CommitEntry, GoOptions, HistoryInstance, NavAnnotation, NavGo, NavigateDetail, NavLocation, NavSource, TrailEntry, } from "./handle.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dojo-ng/history",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Dojo NG navigation history: real paths with pushState, Back and Forward that skip skimmed pages, and hooks for tracking",
   "type": "module",
   "main": "./dist/index.js",