@dojo-ng/history 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# @dojo-ng/history
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Navigation history for single-page apps: real paths with `pushState`, Back and Forward that skip
+pages the user only skimmed, and hooks for tracking. It publishes the location on a
+[`@dojo-ng/pubsub`](https://www.npmjs.com/package/@dojo-ng/pubsub) bus. Your app decides what to show.
+
+Part of the [Dojo NG framework](https://foss.heptapod.net/dojo-ng/framework) packages: plain ESM
+and no Lit. BSD-3-Clause.
+
+## Install
+
+```bash
+npm install @dojo-ng/history @dojo-ng/pubsub
+```
+
+## Usage
+
+```js
+import { createPubSub } from "@dojo-ng/pubsub";
+import { installHistory, match } from "@dojo-ng/history";
+
+const bus = createPubSub();
+const history = installHistory(bus);
+
+// Follow the location. The current one arrives at once, so this also covers a reload.
+history.subscribe((location) => {
+  const order = match("/orders/:id", location.path);
+  if (order) showOrder(order.id);
+});
+
+history.go("/orders/7");   // pushes /orders/7 and publishes the new location
+history.back();
+```
+
+Call `installHistory` once, at startup. A second call logs a warning and returns the first
+instance, because there is one history stack.
+
+## Real paths need a server fallback
+
+Every navigation is a real URL. A reload, a pasted link, or a bookmark asks the server for that
+path, so the server must answer every route your app uses with the app itself. Without that, a
+reload on `/orders/7` is a 404. The app must also be able to render a view from the path alone.
+The [playground](playground/server.mjs) has a ten-line example.
+
+## The bus
+
+| Topic | Payload | Meaning |
+|---|---|---|
+| `nav:go` | `{ path, state?, trail?, replace? }` | Navigate. Anything can publish this. `history.go(path, state)` is a shortcut. |
+| `nav:location` | `{ path, state, index, committed, source, trail? }` | The location changed. |
+
+- `path` is the app path: no `base`, but it keeps any `?query` and `#hash` you gave to `go`.
+- `source` is `"go"` (a `nav:go`), `"pop"` (Back or Forward), or `"load"` (the page opened).
+- `index` is the entry's position in the stack. The entry the app landed on is 0.
+- `committed` is `false` while the entry is provisional (see Dwell). When it commits,
+  `nav:location` is published again with `committed: true`.
+- The bus keeps the last value, so a view that subscribes late still gets the current location.
+
+Only a `nav:go` writes to the browser's history. A `popstate` publishes `nav:location` and does
+nothing else, so Back never adds an entry.
+
+## The history object
+
+`installHistory(bus, options)` returns:
+
+- `go(path, state?, { replace?, trail? }?)`, `back()`, `forward()`
+- `subscribe(fn)` returns an unsubscribe function
+- `current`: the latest `nav:location` payload, or `undefined` before the first one
+- `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` (`#` 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
+- `destroy()`: remove the listeners and unregister. For tests.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `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. |
+
+## Dwell: skimmed pages stay off the stack
+
+A browser cannot remove an entry from history, but it can replace the current one. So a new entry
+is provisional until the user has stayed on it for `dwellMs`. If `go` runs while the current entry
+is provisional, the new path replaces it instead of pushing. Open A, read it, then click through B, C
+and D quickly and settle on E: the stack holds A and E, and Back from E goes to A.
+
+- The entry the app lands on is committed at once.
+- An entry reached by Back or Forward is committed. It already earned its place.
+- `commit()` commits early, for when the user clearly engaged (typing in a form, for example).
+- Only visible time counts. The timer pauses while the tab is hidden and resumes with the time that was left.
+- `go(path, state, { replace: true })` on a provisional entry replaces it and restarts the timer. On
+  an entry that has already committed, the replacement commits too and keeps its place.
+- `dwellMs: 0` pushes every entry, as a browser does.
+
+## Hooks
+
+`onCommit({ path, state, trail? })` runs once per entry that commits. It never runs for a skimmed
+entry or for the landing entry. This is the place to send a location to a server. This package
+ships no server code.
+
+`resolve(path)` is async. When the page opens on an entry with no state of ours (a new tab, a
+pasted link, a bookmark), it is awaited before the first `nav:location` (`source: "load"`), and its
+result becomes the entry's state. If it rejects, the error is logged and the bare path is
+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
+import { match } from "@dojo-ng/history";
+
+match("/orders/:id", "/orders/42");          // { id: "42" }
+match("/files/*", "/files/a/b");             // { "*": "a/b" }
+match("/orders/:id", "/orders");             // null
+```
+
+Static segments, `:name` params (decoded with `decodeURIComponent`), and a trailing `*` that takes
+the rest, zero or more segments. A trailing slash on either side is ignored. Pass a pathname: a
+`?query` or `#hash` is not stripped. Navigation never calls `match`; mapping a path to a view is the app's job.
+
+## For components: the handle subpath
+
+```js
+import { getHistory, whenHistory } from "@dojo-ng/history/handle";
+```
+
+`getHistory()` returns the installed instance or `undefined`. `whenHistory()` returns a promise
+that resolves at install. The subpath also exports the types and imports nothing, so a component
+that only reads the location does not pull in the rest of the package. The instance is stored on
+`globalThis[Symbol.for("dojo-ng.history")]`, so two copies of the package in one bundle share one.
+
+## The dj-navigate event
+
+A component that has a path does not need the instance. It dispatches a bubbling, composed
+`dj-navigate` event, and `installHistory` listens for it on `document`:
+
+```js
+this.dispatchEvent(new CustomEvent("dj-navigate", {
+  detail: { path: "/orders/7", state: undefined, trail: [{ path: "/orders", label: "Orders" }, { path: "/orders/7", label: "Order 7" }], replace: false },
+  bubbles: true,
+  composed: true,
+}));
+```
+
+It becomes a `nav:go`. `trail` is stored in the entry's state, so it comes back on Back, Forward,
+and a same-tab reload. Other keys in `detail` (such as `label`) are ignored here.
+
+## Another router on the page
+
+If something else seems to be writing history, one `console.warn` per kind of signal is logged and
+the layer carries on: `history.pushState` or `replaceState` is not native; Back or Forward lands
+on an entry this layer did not create; or the location changed without a `nav:go`. This package
+never patches `pushState`.
+
+## Playground
+
+```bash
+cd packages/history
+npm run build
+npm run playground     # http://localhost:8902/
+```

package/dist/handle.d.ts

@@ -0,0 +1,88 @@
+/** One step of the path from the root to a node, carried in navigation state. */
+export interface TrailEntry {
+    path: string;
+    label: string;
+}
+/** Where a `NavLocation` came from: a `nav:go`, a Back/Forward (`pop`), or the install itself. */
+export type NavSource = "go" | "pop" | "load";
+/** The payload of every `nav:location` publish. `path` never includes the `base` option. */
+export interface NavLocation {
+    path: string;
+    /** The state passed to `go`, or the result of `resolve`. `undefined` when there is none. */
+    state: unknown;
+    /** Position of this entry in the stack, 0 for the entry the app landed on. */
+    index: number;
+    /** False while the entry is provisional (see `dwellMs`). */
+    committed: boolean;
+    source: NavSource;
+    /** Root-to-node trail, when whoever navigated supplied one. */
+    trail?: TrailEntry[];
+}
+/** What `annotate` can change on the current entry. */
+export interface NavAnnotation {
+    state?: unknown;
+    trail?: TrailEntry[];
+}
+/** The payload of `nav:go`, and of the `dj-navigate` event detail (which may carry extra keys). */
+export interface NavGo {
+    path: string;
+    state?: unknown;
+    trail?: TrailEntry[];
+    replace?: boolean;
+}
+/** The `detail` of the `dj-navigate` event a component dispatches. `label` is for whoever listens; history ignores it. */
+export interface NavigateDetail extends NavGo {
+    label?: string;
+}
+export interface GoOptions {
+    /** Replace the current entry instead of pushing a new one. */
+    replace?: boolean;
+    trail?: TrailEntry[];
+}
+/** What is passed to `onCommit` when an entry commits. */
+export interface CommitEntry {
+    path: string;
+    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;
+    back(): void;
+    forward(): void;
+    /** Commit the current entry now, without waiting out the dwell time. */
+    commit(): void;
+    /** Follow the location. The current one is delivered at once. Returns an unsubscribe function. */
+    subscribe(fn: (location: NavLocation) => void): () => void;
+    /** The current location, or `undefined` until the first one is published. */
+    readonly current: NavLocation | undefined;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    /**
+     * 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;
+    /** Remove listeners and unregister. For tests. */
+    destroy(): void;
+}
+/** The installed instance, or `undefined` when `installHistory` has not run. */
+export declare function getHistory(): HistoryInstance | undefined;
+/** Resolves with the instance: at once if installed, otherwise when `installHistory` runs. */
+export declare function whenHistory(): Promise<HistoryInstance>;
+/** @internal Called by `installHistory`. Not part of the public API. */
+export declare function registerHistory(instance: HistoryInstance): void;
+/** @internal Called by `destroy()`. Only removes the registration if it is still `instance`. */
+export declare function unregisterHistory(instance: HistoryInstance): void;

package/dist/handle.js

@@ -0,0 +1,44 @@
+// The subpath components import: `@dojo-ng/history/handle`. It holds the types, the lookup of the
+// installed instance, and the promise that resolves at install. It imports nothing (no pub/sub, no
+// install code), so a component that only reads the location pulls in a few lines, not the package.
+//
+// The instance lives on `globalThis[Symbol.for("dojo-ng.history")]` (that is `window` in a
+// browser), so two copies of the package in one bundle agree on one instance (decision D3). The
+// callbacks waiting for an install live under a second well-known symbol for the same reason.
+const INSTANCE_KEY = Symbol.for("dojo-ng.history");
+const WAITERS_KEY = Symbol.for("dojo-ng.history.waiters");
+function slot() {
+    return globalThis;
+}
+/** The installed instance, or `undefined` when `installHistory` has not run. */
+export function getHistory() {
+    return slot()[INSTANCE_KEY];
+}
+/** Resolves with the instance: at once if installed, otherwise when `installHistory` runs. */
+export function whenHistory() {
+    const installed = getHistory();
+    if (installed)
+        return Promise.resolve(installed);
+    return new Promise((resolve) => {
+        const s = slot();
+        const waiters = s[WAITERS_KEY] ?? [];
+        waiters.push(resolve);
+        s[WAITERS_KEY] = waiters;
+    });
+}
+/** @internal Called by `installHistory`. Not part of the public API. */
+export function registerHistory(instance) {
+    const s = slot();
+    s[INSTANCE_KEY] = instance;
+    const waiters = s[WAITERS_KEY];
+    s[WAITERS_KEY] = undefined;
+    if (waiters)
+        for (const resolve of waiters)
+            resolve(instance);
+}
+/** @internal Called by `destroy()`. Only removes the registration if it is still `instance`. */
+export function unregisterHistory(instance) {
+    const s = slot();
+    if (s[INSTANCE_KEY] === instance)
+        s[INSTANCE_KEY] = undefined;
+}

package/dist/history.d.ts

@@ -0,0 +1,82 @@
+import type { PubSub } from "@dojo-ng/pubsub";
+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: {
+        pushState(state: unknown, title: string, url?: string | null): void;
+        replaceState(state: unknown, title: string, url?: string | null): void;
+        back(): void;
+        forward(): void;
+        go(delta: number): void;
+        scrollRestoration?: "auto" | "manual";
+        readonly state: unknown;
+    };
+    location: {
+        readonly pathname: string;
+        readonly search: string;
+        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;
+    };
+    readonly sessionStorage?: {
+        getItem(key: string): string | null;
+        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;
+    /** Default `globalThis.window`. Exists so tests can inject a fake. */
+    window?: HistoryWindow;
+    /** How long (visible) milliseconds an entry must stay current before it is committed. Default 3000. 0 turns skimming off. */
+    dwellMs?: number;
+    /** Called once per entry when it commits. Never for a skimmed entry, never for the landing entry. */
+    onCommit?: (entry: CommitEntry) => void;
+    /**
+     * Called at install when the landing entry carries no state of ours (a new tab, a pasted link, a
+     * 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

@@ -0,0 +1,642 @@
+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() {
+    return `${Date.now().toString(36)}-${(++idCounter).toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function readStamp(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const stamp = raw.__djnav;
+    if (!isRecord(stamp) || typeof stamp.id !== "string" || typeof stamp.index !== "number")
+        return undefined;
+    return { id: stamp.id, index: stamp.index };
+}
+function isNative(fn) {
+    try {
+        return Function.prototype.toString.call(fn).includes("[native code]");
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeBase(base) {
+    if (!base)
+        return "";
+    const trimmed = base.replace(/\/+$/, "");
+    return trimmed === "" || trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function installHistory(bus, options = {}) {
+    const existing = getHistory();
+    if (existing) {
+        if (!DUPLICATE_INSTALL_WARNED.has(existing)) {
+            DUPLICATE_INSTALL_WARNED.add(existing);
+            console.warn("[@dojo-ng/history] installHistory was called more than once. There is one history stack; returning the first instance.");
+        }
+        return existing;
+    }
+    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 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;
+    let expectedPlace = "";
+    let destroyed = false;
+    let timer;
+    let remaining = dwellMs;
+    let startedAt = 0;
+    // --- helpers -------------------------------------------------------------------------------
+    function warnOnce(signal, message) {
+        if (warned.has(signal))
+            return;
+        warned.add(signal);
+        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);
+            return rest.startsWith("/") ? rest : `/${rest}`;
+        }
+        return full;
+    }
+    function place() {
+        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 };
+    }
+    /** The one place that writes to the browser's history. Called from `onGo`, install, and annotate; never from `onPop`. */
+    function writeEntry(mode, entry, url) {
+        if (mode === "push")
+            win.history.pushState(stateFor(entry), "", url);
+        else
+            win.history.replaceState(stateFor(entry), "", url);
+    }
+    function entryFromState(raw, stamp) {
+        const record = raw;
+        return {
+            id: stamp.id,
+            index: stamp.index,
+            path: currentPath(),
+            state: record.state,
+            trail: Array.isArray(record.trail) ? record.trail : undefined,
+            committed: !provisionalIds.has(stamp.id),
+            source: "pop",
+        };
+    }
+    function readMax() {
+        try {
+            const value = win.sessionStorage?.getItem(MAX_INDEX_KEY);
+            if (value === null || value === undefined)
+                return undefined;
+            const n = Number(value);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function writeMax(n) {
+        try {
+            win.sessionStorage?.setItem(MAX_INDEX_KEY, String(n));
+        }
+        catch {
+            // Storage can be blocked. canGoForward is then false, which is harmless.
+        }
+    }
+    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);
+    }
+    function fireCommit(entry) {
+        if (!options.onCommit)
+            return;
+        try {
+            options.onCommit({ path: entry.path, state: entry.state, ...(entry.trail ? { trail: entry.trail } : {}) });
+        }
+        catch (err) {
+            console.error("[@dojo-ng/history] onCommit threw:", err);
+        }
+    }
+    // --- dwell ---------------------------------------------------------------------------------
+    function isVisible() {
+        return win.document.visibilityState !== "hidden";
+    }
+    function stopTimer() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function runTimer() {
+        startedAt = Date.now();
+        timer = setTimeout(() => {
+            timer = undefined;
+            commitCurrent();
+        }, remaining);
+    }
+    /** Start counting dwell time for a provisional entry. Counts visible time only. */
+    function startDwell() {
+        stopTimer();
+        remaining = dwellMs;
+        if (isVisible())
+            runTimer();
+    }
+    function onVisibility() {
+        if (destroyed)
+            return;
+        if (!isVisible()) {
+            if (timer !== undefined) {
+                stopTimer();
+                remaining = Math.max(0, remaining - (Date.now() - startedAt));
+            }
+        }
+        else if (!cur.committed && timer === undefined) {
+            runTimer();
+        }
+    }
+    function commitCurrent() {
+        if (destroyed || cur.committed)
+            return;
+        stopTimer();
+        cur.committed = true;
+        provisionalIds.delete(cur.id);
+        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) {
+            warnOnce("foreign-location", "The location changed without a nav:go, so another router or script may be pushing history");
+        }
+    }
+    // --- inputs --------------------------------------------------------------------------------
+    function onGo(request) {
+        if (destroyed || !request || typeof request.path !== "string")
+            return;
+        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 = !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,
+            path: request.path,
+            state: request.state,
+            trail: request.trail,
+            committed: false,
+            source: "go",
+        };
+        provisionalIds.delete(previous.id);
+        stopTimer();
+        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 || adopt || (replace && previous.committed);
+        if (commitNow) {
+            entry.committed = true;
+            publish();
+            fireCommit(entry);
+        }
+        else {
+            provisionalIds.add(entry.id);
+            publish();
+            startDwell();
+        }
+        afterNavigation(entry);
+    }
+    function onPop() {
+        if (destroyed)
+            return;
+        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) {
+            warnOnce("foreign-entry", "Back or Forward landed on a history entry this layer did not create, so another router or script may be pushing history");
+            // Keeps the id of the entry we were on, so a later Back onto a stamped entry that is
+            // already "current" still reads as history changing without a nav:go.
+            entry = {
+                id: cur.id,
+                index: cur.index,
+                path: currentPath(),
+                state: undefined,
+                committed: true,
+                source: "pop",
+            };
+        }
+        else {
+            if (stamp.id === cur.id) {
+                warnOnce("foreign-location", "Back landed on the entry already current, so history changed without a nav:go");
+            }
+            entry = entryFromState(raw, stamp);
+            if (!entry.committed) {
+                entry.committed = true;
+                provisionalIds.delete(entry.id);
+                newlyCommitted = true;
+            }
+        }
+        entry.source = "pop";
+        cur = entry;
+        expectedPlace = place();
+        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;
+        if (!detail || typeof detail.path !== "string")
+            return;
+        bus.publish("nav:go", {
+            path: detail.path,
+            state: detail.state,
+            trail: detail.trail,
+            replace: detail.replace === true,
+        });
+    }
+    // --- the instance --------------------------------------------------------------------------
+    const instance = {
+        go(path, state, goOptions) {
+            bus.publish("nav:go", { path, state, trail: goOptions?.trail, replace: goOptions?.replace === true });
+        },
+        back() {
+            win.history.back();
+        },
+        forward() {
+            win.history.forward();
+        },
+        commit: commitCurrent,
+        subscribe(fn) {
+            return bus.subscribe("nav:location", (location) => fn(location));
+        },
+        get current() {
+            return last;
+        },
+        get canGoBack() {
+            return cur.index > 0;
+        },
+        get canGoForward() {
+            const max = readMax();
+            return max !== undefined && cur.index < max;
+        },
+        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;
+            if ("state" in partial)
+                cur.state = partial.state;
+            if ("trail" in partial)
+                cur.trail = partial.trail;
+            writeEntry("replace", cur);
+            publish();
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            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);
+        },
+    };
+    // --- install -------------------------------------------------------------------------------
+    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;
+    if (stamp) {
+        cur = { ...entryFromState(raw, stamp), committed: true, source: "load" };
+    }
+    else {
+        // A fresh tab, pasted link, or bookmark. Stamp the entry so none ever has null state (app3 lesson 5).
+        fresh = true;
+        cur = { id: newId(), index: 0, path: currentPath(), state: undefined, committed: true, source: "load" };
+        writeEntry("replace", cur);
+        writeMax(0);
+    }
+    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);
+    if (fresh && options.resolve) {
+        const landing = cur;
+        new Promise((resolve) => resolve(options.resolve(landing.path))).then((result) => {
+            if (destroyed || cur !== landing)
+                return;
+            if (result !== undefined) {
+                landing.state = result;
+                writeEntry("replace", landing);
+            }
+            publish();
+        }, (err) => {
+            console.error("[@dojo-ng/history] resolve rejected; publishing the bare path:", err);
+            if (destroyed || cur !== landing)
+                return;
+            publish();
+        });
+    }
+    else {
+        publish();
+        if (!fresh)
+            afterNavigation(cur);
+    }
+    return instance;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+export { installHistory } from "./history.js";
+export { match } from "./match.js";
+export { getHistory, whenHistory } from "./handle.js";

package/dist/match.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Match a path against a pattern of static segments, `:name` params, and an optional trailing `*`.
+ * Returns the params, or `null` when the path does not match. Params are decoded with
+ * `decodeURIComponent`; a malformed escape is a non-match. A trailing slash on either side is
+ * ignored. `*` takes the rest of the path, zero or more segments, under the key `"*"`.
+ *
+ * Pass a pathname. A `?query` or `#hash` is not stripped.
+ */
+export declare function match(pattern: string, path: string): Record<string, string> | null;

package/dist/match.js

@@ -0,0 +1,58 @@
+// Path matching. A separate export that navigation never calls (decision D10): mapping a path to a
+// view stays the app's job, and this is only a helper for doing it.
+function segments(path) {
+    const parts = path.split("/");
+    if (parts[0] === "")
+        parts.shift();
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Match a path against a pattern of static segments, `:name` params, and an optional trailing `*`.
+ * Returns the params, or `null` when the path does not match. Params are decoded with
+ * `decodeURIComponent`; a malformed escape is a non-match. A trailing slash on either side is
+ * ignored. `*` takes the rest of the path, zero or more segments, under the key `"*"`.
+ *
+ * Pass a pathname. A `?query` or `#hash` is not stripped.
+ */
+export function match(pattern, path) {
+    const want = segments(pattern);
+    const have = segments(path);
+    const rest = want[want.length - 1] === "*";
+    const fixed = rest ? want.slice(0, -1) : want;
+    if (rest ? have.length < fixed.length : have.length !== fixed.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < fixed.length; i++) {
+        const piece = fixed[i];
+        if (piece.length > 1 && piece[0] === ":") {
+            const value = decode(have[i]);
+            if (value === null)
+                return null;
+            params[piece.slice(1)] = value;
+        }
+        else if (piece !== have[i]) {
+            return null;
+        }
+    }
+    if (rest) {
+        const decoded = [];
+        for (const part of have.slice(fixed.length)) {
+            const value = decode(part);
+            if (value === null)
+                return null;
+            decoded.push(value);
+        }
+        params["*"] = decoded.join("/");
+    }
+    return params;
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@dojo-ng/history",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./handle": {
+      "types": "./dist/handle.d.ts",
+      "default": "./dist/handle.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "dojo",
+    "history",
+    "navigation",
+    "pushstate",
+    "spa",
+    "esm"
+  ],
+  "repository": {
+    "type": "hg",
+    "url": "https://foss.heptapod.net/dojo-ng/framework"
+  },
+  "dependencies": {
+    "@dojo-ng/pubsub": "^0.1.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:browser": "npm run build && web-test-runner",
+    "playground": "node playground/server.mjs",
+    "prepublishOnly": "npm run build"
+  }
+}