@reactra/router 0.1.0-alpha.0

package/dist/scrollManager.js

@@ -0,0 +1,189 @@
+// @reactra/router — scroll restoration (Wave 3, §2b).
+//
+// Owner spec: reactra-router-spec.md §3.5 (per-page modes) + §13.1
+// (RouterConfig `scrollRestoration` block).
+//
+// Scope of this module: the **app-wide default mode** (`auto` / `top` /
+// `manual`) + storage management. Per-page `meta { scrollRestoration:
+// "manual" }` overrides need the meta classifier (phase-2.md §2a — still
+// open), so this stage ships the global default. When the classifier
+// lands, the navigate-integration call site reads the per-route override
+// from the matched route's resolved meta and passes that mode in here
+// instead of `cfg.defaultMode`.
+//
+// Storage shape:
+//   sessionStorage[cfg.scrollKey] = JSON { [historyKey]: { x, y } }
+//
+// `historyKey` is a stable id per history entry — assigned to
+// `history.state.key` on push, persisted across the back/forward stack,
+// and read back on `popstate`. This is the same approach Remix /
+// Next.js use, with the same trade-off: a stray `history.replaceState`
+// that overwrites our key without preserving it loses scroll for that
+// entry — we treat that as the user's choice (e.g. an analytics lib
+// rewriting state).
+//
+// Mode behaviour (Router §3.5 table):
+//
+//   auto    | push: scroll to top         | pop: restore saved (top if none)
+//   top     | push: scroll to top         | pop: scroll to top
+//   manual  | push: no scroll             | pop: no scroll  (app controls)
+//
+// In test / Node environments where `window` / `sessionStorage` are
+// undefined, every method is a no-op so the same code runs cleanly
+// under `bun test`.
+// ─── Storage helpers ──────────────────────────────────────────────────────
+const hasSessionStorage = () => typeof globalThis !== "undefined" &&
+    typeof globalThis.sessionStorage !== "undefined";
+const readMap = (storageKey) => {
+    if (!hasSessionStorage())
+        return {};
+    try {
+        const raw = sessionStorage.getItem(storageKey);
+        if (raw === null)
+            return {};
+        const parsed = JSON.parse(raw);
+        // Defensive: a foreign actor may have written non-object data.
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+const writeMap = (storageKey, map) => {
+    if (!hasSessionStorage())
+        return;
+    try {
+        sessionStorage.setItem(storageKey, JSON.stringify(map));
+    }
+    catch {
+        // Quota exceeded / disabled storage — silently swallow; scroll
+        // restoration is a polish feature, not a correctness invariant.
+    }
+};
+// ─── Key generation ───────────────────────────────────────────────────────
+let counter = 0;
+/**
+ * Generate a fresh history-entry key. `crypto.randomUUID` when available
+ * (browser, modern Node); falls back to a monotone counter so tests in a
+ * minimal environment still get unique keys. The format isn't load-bearing
+ * — the navigate-integration site only uses it as an opaque sessionStorage
+ * key.
+ */
+export const generateHistoryKey = () => {
+    if (typeof globalThis !== "undefined" &&
+        typeof globalThis.crypto?.randomUUID === "function") {
+        return globalThis.crypto.randomUUID();
+    }
+    counter += 1;
+    return `key-${counter}`;
+};
+export const createScrollManager = (cfg) => {
+    const scrollWindowTo = (x, y) => {
+        if (typeof window === "undefined")
+            return;
+        if (typeof window.scrollTo === "function")
+            window.scrollTo(x, y);
+    };
+    return {
+        saveCurrent(historyKey) {
+            if (typeof window === "undefined")
+                return;
+            const map = readMap(cfg.scrollKey);
+            map[historyKey] = {
+                x: window.scrollX ?? 0,
+                y: window.scrollY ?? 0,
+            };
+            writeMap(cfg.scrollKey, map);
+        },
+        restoreFor(historyKey) {
+            const map = readMap(cfg.scrollKey);
+            const saved = map[historyKey];
+            if (!saved)
+                return false;
+            scrollWindowTo(saved.x, saved.y);
+            return true;
+        },
+        scrollToTop() {
+            scrollWindowTo(0, 0);
+        },
+        applyForNavigation(historyKey, navKind, modeOverride) {
+            const mode = modeOverride ?? cfg.defaultMode;
+            if (mode === "manual")
+                return;
+            if (mode === "top") {
+                this.scrollToTop();
+                return;
+            }
+            // mode === "auto"
+            if (navKind === "pop") {
+                const restored = historyKey !== null && this.restoreFor(historyKey);
+                if (!restored)
+                    this.scrollToTop();
+                return;
+            }
+            // push / replace → top
+            this.scrollToTop();
+        },
+    };
+};
+// ─── History-state key helpers ────────────────────────────────────────────
+const HISTORY_KEY_FIELD = "__reactraScrollKey";
+/**
+ * Read the key on the current history entry, or null if absent (e.g.
+ * an entry created before scroll restoration was wired in, or one
+ * overwritten by a foreign `replaceState`). The caller's mode handler
+ * treats `null` as "no saved scroll" — auto mode then falls back to
+ * scroll-to-top.
+ */
+export const readHistoryKey = () => {
+    if (typeof window === "undefined")
+        return null;
+    const state = window.history.state;
+    const v = state?.[HISTORY_KEY_FIELD];
+    return typeof v === "string" ? v : null;
+};
+/**
+ * Ensure the current history entry carries a key. If it already does,
+ * returns the existing key. Otherwise generates one + `replaceState`s
+ * the entry to write it. Returns the key in use.
+ */
+export const ensureHistoryKey = () => {
+    if (typeof window === "undefined")
+        return generateHistoryKey();
+    const existing = readHistoryKey();
+    if (existing !== null)
+        return existing;
+    const key = generateHistoryKey();
+    const state = window.history.state ?? {};
+    window.history.replaceState({ ...state, [HISTORY_KEY_FIELD]: key }, "", window.location.href);
+    return key;
+};
+/**
+ * Push a new history entry with a fresh key embedded. Use this from
+ * `navigate()` in place of bare `pushState`.
+ */
+export const pushStateWithKey = (extraState, url) => {
+    const key = generateHistoryKey();
+    if (typeof window === "undefined")
+        return key;
+    window.history.pushState({ ...extraState, [HISTORY_KEY_FIELD]: key }, "", url);
+    return key;
+};
+/**
+ * Replace the current history entry with a fresh state object, embedding
+ * the SAME key as the entry being replaced. If the entry has no key yet,
+ * a fresh one is generated. Returns the key in use.
+ */
+export const replaceStateWithKey = (extraState, url) => {
+    if (typeof window === "undefined")
+        return generateHistoryKey();
+    const existing = readHistoryKey();
+    const key = existing ?? generateHistoryKey();
+    window.history.replaceState({ ...extraState, [HISTORY_KEY_FIELD]: key }, "", url);
+    return key;
+};
+// Test-only re-exports.
+export const __readMap = readMap;
+export const __writeMap = writeMap;
+export const __HISTORY_KEY_FIELD = HISTORY_KEY_FIELD;
+//# sourceMappingURL=scrollManager.js.map

package/dist/scrollManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollManager.js","sourceRoot":"","sources":["../src/scrollManager.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,mEAAmE;AACnE,4CAA4C;AAC5C,EAAE;AACF,wEAAwE;AACxE,sEAAsE;AACtE,yEAAyE;AACzE,qEAAqE;AACrE,yEAAyE;AACzE,sEAAsE;AACtE,gCAAgC;AAChC,EAAE;AACF,iBAAiB;AACjB,oEAAoE;AACpE,EAAE;AACF,8DAA8D;AAC9D,wEAAwE;AACxE,iEAAiE;AACjE,uEAAuE;AACvE,sEAAsE;AACtE,oEAAoE;AACpE,oBAAoB;AACpB,EAAE;AACF,sCAAsC;AACtC,EAAE;AACF,6EAA6E;AAC7E,+DAA+D;AAC/D,2EAA2E;AAC3E,EAAE;AACF,oEAAoE;AACpE,mEAAmE;AACnE,oBAAoB;AAsBpB,6EAA6E;AAE7E,MAAM,iBAAiB,GAAG,GAAY,EAAE,CACtC,OAAO,UAAU,KAAK,WAAW;IACjC,OAAQ,UAA2C,CAAC,cAAc,KAAK,WAAW,CAAA;AAEpF,MAAM,OAAO,GAAG,CAAC,UAAkB,EAAY,EAAE;IAC/C,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAO,EAAE,CAAA;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QAC9C,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,EAAE,CAAA;QAC3B,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACvC,+DAA+D;QAC/D,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,EAAE,CAAA;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,CAAC,UAAkB,EAAE,GAAa,EAAQ,EAAE;IAC3D,IAAI,CAAC,iBAAiB,EAAE;QAAE,OAAM;IAChC,IAAI,CAAC;QACH,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,gEAAgE;IAClE,CAAC;AACH,CAAC,CAAA;AAED,6EAA6E;AAE7E,IAAI,OAAO,GAAG,CAAC,CAAA;AAEf;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAW,EAAE;IAC7C,IACE,OAAO,UAAU,KAAK,WAAW;QACjC,OAAQ,UAAyD,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,EACnG,CAAC;QACD,OAAQ,UAAuD,CAAC,MAAM,CAAC,UAAU,EAAE,CAAA;IACrF,CAAC;IACD,OAAO,IAAI,CAAC,CAAA;IACZ,OAAO,OAAO,OAAO,EAAE,CAAA;AACzB,CAAC,CAAA;AAwBD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAwB,EAAiB,EAAE;IAC7E,MAAM,cAAc,GAAG,CAAC,CAAS,EAAE,CAAS,EAAQ,EAAE;QACpD,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAM;QACzC,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU;YAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAClE,CAAC,CAAA;IACD,OAAO;QACL,WAAW,CAAC,UAAU;YACpB,IAAI,OAAO,MAAM,KAAK,WAAW;gBAAE,OAAM;YACzC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YAClC,GAAG,CAAC,UAAU,CAAC,GAAG;gBAChB,CAAC,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC;gBACtB,CAAC,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC;aACvB,CAAA;YACD,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;QAC9B,CAAC;QACD,UAAU,CAAC,UAAU;YACnB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YAClC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,CAAA;YAC7B,IAAI,CAAC,KAAK;gBAAE,OAAO,KAAK,CAAA;YACxB,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;YAChC,OAAO,IAAI,CAAA;QACb,CAAC;QACD,WAAW;YACT,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACtB,CAAC;QACD,kBAAkB,CAAC,UAAU,EAAE,OAAO,EAAE,YAAY;YAClD,MAAM,IAAI,GAAG,YAAY,IAAI,GAAG,CAAC,WAAW,CAAA;YAC5C,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAM;YAC7B,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBACnB,IAAI,CAAC,WAAW,EAAE,CAAA;gBAClB,OAAM;YACR,CAAC;YACD,kBAAkB;YAClB,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;gBACtB,MAAM,QAAQ,GAAG,UAAU,KAAK,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAA;gBACnE,IAAI,CAAC,QAAQ;oBAAE,IAAI,CAAC,WAAW,EAAE,CAAA;gBACjC,OAAM;YACR,CAAC;YACD,uBAAuB;YACvB,IAAI,CAAC,WAAW,EAAE,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,6EAA6E;AAE7E,MAAM,iBAAiB,GAAG,oBAAoB,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAkB,EAAE;IAChD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAA;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAmD,CAAA;IAChF,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC,iBAAiB,CAAC,CAAA;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACzC,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAW,EAAE;IAC3C,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,kBAAkB,EAAE,CAAA;IAC9D,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;IACjC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAA;IACtC,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAA;IAChC,MAAM,KAAK,GAAI,MAAM,CAAC,OAAO,CAAC,KAAwC,IAAI,EAAE,CAAA;IAC5E,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC7F,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,UAAmC,EACnC,GAAW,EACH,EAAE;IACV,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAA;IAChC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,GAAG,CAAA;IAC7C,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAA;IAC9E,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,UAAmC,EACnC,GAAW,EACH,EAAE;IACV,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,kBAAkB,EAAE,CAAA;IAC9D,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;IACjC,MAAM,GAAG,GAAG,QAAQ,IAAI,kBAAkB,EAAE,CAAA;IAC5C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAA;IACjF,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA;AAED,wBAAwB;AACxB,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAA;AAChC,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAA;AAClC,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAA"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@reactra/router",
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akhilshastri/reactra.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://reactra-docs.vercel.app",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "sideEffects": false,
+  "description": "Reactra router runtime — file-based routing, params/query, navigation, and middleware."
+}