ignotum 0.0.13 → 0.0.15

package/src/client/router-history.ts

@@ -0,0 +1,152 @@
+import * as Versioned from "@ignotum/contracts/versioned";
+import { Deferred, Effect, Schema } from "effect";
+
+const HistoryEntryV1 = Schema.Struct({ formatVersion: Schema.Literal(1), key: Schema.String });
+const HistoryEntryV2 = Schema.Struct({
+  formatVersion: Schema.Literal(2),
+  key: Schema.String,
+  index: Schema.NullOr(Schema.Int),
+});
+const HistoryEntry = Versioned.upgrade(
+  Versioned.initial(HistoryEntryV1),
+  HistoryEntryV2,
+  (old) => ({
+    formatVersion: 2 as const,
+    key: old.key,
+    index: null,
+  }),
+);
+const HistoryState = Schema.Struct({ __ignotumRouter: HistoryEntry });
+const StateObject = Schema.Record(Schema.String, Schema.Unknown);
+export interface HistoryPosition {
+  readonly key: string;
+  readonly index: number;
+  readonly href: string;
+}
+const hrefOf = (browser: Window) =>
+  `${browser.location.pathname}${browser.location.search}${browser.location.hash}`;
+
+/** Serializes router corrections to native traversal without adding duplicate entries. */
+export class RouterHistory {
+  committed: HistoryPosition;
+  private actual: HistoryPosition;
+  private readonly positions = new Map<string, number>();
+  private seeking: { position: HistoryPosition; done: Deferred.Deferred<boolean> } | undefined;
+  private readonly originalScrollRestoration;
+  private direction = -1;
+  private scrollPending = false;
+  private expectedKey: string | undefined;
+  readonly scroll = new Map<string, { x: number; y: number }>();
+  constructor(
+    private readonly browser: Window,
+    private readonly onTraversal: (position: HistoryPosition) => void,
+  ) {
+    const parsed = Schema.decodeUnknownOption(HistoryState)(browser.history.state);
+    const entry = parsed._tag === "Some" ? parsed.value.__ignotumRouter : undefined;
+    this.actual = this.committed = {
+      key: entry?.key ?? browser.crypto.randomUUID(),
+      index: entry?.index ?? 0,
+      href: hrefOf(browser),
+    };
+    this.write(this.actual, false);
+    this.originalScrollRestoration = browser.history.scrollRestoration;
+    browser.history.scrollRestoration = "manual";
+    browser.addEventListener("popstate", this.onPop);
+    browser.addEventListener("scroll", this.saveScroll);
+  }
+  private write(position: HistoryPosition, push: boolean): void {
+    const parsed = Schema.decodeUnknownOption(StateObject)(this.browser.history.state);
+    const owned = {
+      __ignotumRouter: Schema.encodeSync(HistoryEntry)({
+        formatVersion: 2,
+        key: position.key,
+        index: position.index,
+      }),
+    };
+    const state = parsed._tag === "Some" ? { ...parsed.value, ...owned } : owned;
+    if (push) this.browser.history.pushState(state, "", position.href);
+    else this.browser.history.replaceState(state, "", position.href);
+    this.positions.set(position.key, position.index);
+  }
+  saveScroll = (): void => {
+    if (this.scrollPending) return;
+    this.scroll.set(this.committed.key, { x: this.browser.scrollX, y: this.browser.scrollY });
+  };
+  captureScroll(): { x: number; y: number } {
+    this.saveScroll();
+    this.scrollPending = true;
+    return (
+      this.scroll.get(this.committed.key) ?? { x: this.browser.scrollX, y: this.browser.scrollY }
+    );
+  }
+  finishScroll(): void {
+    this.scrollPending = false;
+    this.saveScroll();
+  }
+  restoreSourceScroll(): void {
+    if (!this.scrollPending) return;
+    const saved = this.scroll.get(this.committed.key);
+    if (saved !== undefined) this.browser.scrollTo(saved.x, saved.y);
+    this.finishScroll();
+  }
+  private onPop = (): void => {
+    const parsed = Schema.decodeUnknownOption(HistoryState)(this.browser.history.state);
+    const entry = parsed._tag === "Some" ? parsed.value.__ignotumRouter : undefined;
+    const key = entry?.key ?? this.browser.crypto.randomUUID();
+    const index = entry?.index ?? this.positions.get(key) ?? this.actual.index + this.direction;
+    this.actual = { key, index, href: hrefOf(this.browser) };
+    this.write(this.actual, false);
+    const expected = this.expectedKey;
+    this.expectedKey = undefined;
+    const seeking = this.seeking;
+    if (seeking !== undefined && (expected === key || seeking.position.key === key)) {
+      this.advanceSeek();
+      return;
+    }
+    if (seeking !== undefined) {
+      this.seeking = undefined;
+      Effect.runSync(Deferred.succeed(seeking.done, false));
+    }
+    this.onTraversal(this.actual);
+  };
+  private advanceSeek(): void {
+    const seeking = this.seeking;
+    if (seeking === undefined || this.expectedKey !== undefined) return;
+    if (this.actual.key === seeking.position.key) {
+      this.seeking = undefined;
+      Effect.runSync(Deferred.succeed(seeking.done, true));
+    } else {
+      this.expectedKey = seeking.position.key;
+      this.browser.history.go(seeking.position.index - this.actual.index);
+    }
+  }
+  seek(position: HistoryPosition): Promise<boolean> {
+    if (this.seeking !== undefined) {
+      if (this.seeking.position.key === position.key)
+        return Effect.runPromise(Deferred.await(this.seeking.done));
+      Effect.runSync(Deferred.succeed(this.seeking.done, false));
+    }
+    const done = Deferred.makeUnsafe<boolean>();
+    this.seeking = { position, done };
+    this.advanceSeek();
+    return Effect.runPromise(Deferred.await(done));
+  }
+  commit(position: HistoryPosition, kind: "initial" | "push" | "replace" | "traverse"): void {
+    if (kind === "push" || kind === "replace") this.write(position, kind === "push");
+    this.actual = this.committed = position;
+  }
+  back = (): void => {
+    this.direction = -1;
+    this.browser.history.back();
+  };
+  forward = (): void => {
+    this.direction = 1;
+    this.browser.history.forward();
+  };
+  dispose(): void {
+    this.browser.removeEventListener("popstate", this.onPop);
+    this.browser.removeEventListener("scroll", this.saveScroll);
+    this.browser.history.scrollRestoration = this.originalScrollRestoration;
+    if (this.seeking !== undefined) Effect.runSync(Deferred.succeed(this.seeking.done, false));
+  }
+}