From 91344ea6de3716654be62a65c5c4ce7928679c6e Mon Sep 17 00:00:00 2001
From: Martin Trapp <94928215+martrapp@users.noreply.github.com>
Date: Thu, 5 Sep 2024 11:29:02 +0200
Subject: [PATCH] prepare for 1.0.0

---
 README.md           |  19 +++-
 package.json        |   3 +-
 src/over-the-top.ts | 139 +++++++++------------------
 src/types.ts        |  17 +++-
 src/vanilla.ts      | 222 +++++++++++++++++++++++++++++---------------
 5 files changed, 225 insertions(+), 175 deletions(-)

diff --git a/README.md b/README.md
index 4e2c274..abbb304 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
 # 🚸 ElementCrossing
+
 Transfer selected element states across cross-document view transitions.
 
 ![Build Status](https://github.com/vtbag/element-crossing/actions/workflows/run-tests.yml/badge.svg)
@@ -13,4 +14,20 @@ First official release of this code!
 
 ## What is it?
 
-This library provides a robust solution for maintaining HTML elements and their associated state across cross-document view transitions.
+Boost the smoothness of your cross-document view transitions with the Element Crossing library! No more resetting to static states! This library preserves the current dynamic state of your DOM and CSS properties, ensuring a seamless user experience.
+
+With Element Crossing, you can automatically retain:
+
+- Current form inputs
+- Current scrollbar positions
+- Current state of active CSS animations
+- Current media playback time
+- Current toggle states
+- Current values of dynamically added classes and CSS properties
+- ...and (current) anything else you'd like to carry over from the previous page to the new one!
+
+Simply annotate your elements in the HTML source or DOM, and let the library handle the rest. Keep your users engaged by preserving the exact state they left off, making transitions across documents smoother than ever!
+
+Address any CSS property or DOM element property, any CSS class, or CSS animation.
+
+[View configuration examples](https://vtbag.pages.dev/tools/element-crossing/#applications-with-real-world-examples) and [see the Element Crossing in action](https://vtbag.pages.dev/crossing/vanilla/1/)
\ No newline at end of file
diff --git a/package.json b/package.json
index 2a7304a..41e9a38 100644
--- a/package.json
+++ b/package.json
@@ -9,8 +9,7 @@
   ],
   "exports": {
     ".": "./lib/vanilla.js",
-    "./vanilla": "./lib/vanilla.js",
-    "./over-the-top": "./lib/over-the-top.js"
+    "./experimental": "./lib/over-the-top.js"
   },
   "scripts": {
     "dev": "bin/bundle dev",
diff --git a/src/over-the-top.ts b/src/over-the-top.ts
index 6501560..fd6c5cd 100644
--- a/src/over-the-top.ts
+++ b/src/over-the-top.ts
@@ -1,103 +1,54 @@
-import { Spec } from './types';
-
 top!.__vtbag ??= {};
-top!.__vtbag.elementCrossing ??= {};
-const elementCrossing = top!.__vtbag.elementCrossing!;
 
-console.log('[elc]', 'init');
-if (top === self) {
-	initBorderLands();
-} else if (self.parent === top) {
-	initHeartLand();
-} else {
-	console.log('[elc]', 'neither BorderLands nor HeartLand');
-}
+const crossing = (top!.__vtbag.elementCrossing ??= {
+	storageMap: new Map<string, Element>(),
+	addrWeakMap: new WeakMap<any, string>(),
+	fun: {
+		pseudoAddress(object: object): string {
+			let addr = '0x000000';
+			if (object === null || object === undefined) return addr;
+			while (addr === '0x000000') {
+				addr =
+					crossing.addrWeakMap.get(object) ??
+					'0x' + Math.random().toString(16).slice(2, 8).toUpperCase();
+			}
+			crossing.addrWeakMap.set(object, addr);
+			return addr;
+		},
+		setItem(id: string, element: Element) {
+			crossing.storageMap!.set(id, element);
+		},
+		getItem(id: string): Element | undefined {
+			const element = crossing.storageMap!.get(id);
+			return element;
+		},
+		removeItem(id: string): void {
+			crossing.storageMap!.delete(id);
+		},
+		clear(): void {
+			crossing.storageMap!.clear();
+		},
+	},
+});
+
+top === self && initBorderLands();
 
 function initBorderLands() {
-	console.log('[elc]', 'init BorderLands');
-	addEventListener('pagereveal', () => {
-		console.log('[elc]', 'DOMContentLoaded');
+	top!.addEventListener('pagereveal', () => {
 		const topDoc = top!.document;
-		const root = topDoc.documentElement;
-		root.innerHTML = `<body style="margin:0; overflow=clip"><iframe width=${innerWidth} height=${innerHeight} src="${location.href}"/>`;
+		const lang = topDoc.documentElement.lang;
+		const colorScheme = topDoc.documentElement.style.colorScheme;
+		const root = topDoc.createElement('html');
+		root.innerHTML = `<body style="margin:0; overflow=clip"><iframe width=${innerWidth} height=${innerHeight} style="border:0" src="${location.href}"/>`;
+		crossing.iframe = root.querySelector<HTMLIFrameElement>('iframe')!;
+		root.lang = lang;
 		root.style.overflow = 'clip';
+		root.style.colorScheme = colorScheme;
+		topDoc.documentElement.replaceWith(root);
+		crossing.frameDocument = topDoc.querySelector<HTMLIFrameElement>('iframe')!.contentDocument!;
 	});
-}
-
-function initHeartLand() {
-	console.log('[elc]', 'init HeartLand');
-	self.addEventListener('pageswap', pageSwap, { once: true });
-	self.addEventListener('pagereveal', pageReveal, { once: true });
-}
-
-function pageSwap() {
-	console.log('[elc]', 'pageSwap');
-
-	self.document.querySelectorAll<HTMLElement>('[data-vtbag-x]').forEach((el) => {
-		let id;
-		const specs: Spec[] = [];
-		el
-			.getAttribute('data-vtbag-x')
-			?.split(' ')
-			.forEach((value) => {
-				const [kind, key] = kindAndKey(value);
-				switch (kind) {
-					case 'id':
-						id = key;
-						break;
-					case 'class':
-						specs.push({ kind, key, value: el.classList.contains(key) ? 'true' : 'false' });
-						break;
-					case 'style':
-						specs.push({
-							kind,
-							key,
-							value: '' + (el.style[key as keyof CSSStyleDeclaration] ?? ''),
-						});
-						break;
-					case 'attr':
-						specs.push({ kind, key, value: el.getAttribute(key) ?? '' });
-						break;
-					default:
-						console.error('[crossing]', 'unknown kind', kind);
-						break;
-				}
-			});
+	top!.addEventListener('resize', () => {
+		crossing.iframe!.width = '' + top!.innerWidth;
+		crossing.iframe!.height = '' + top!.innerHeight;
 	});
 }
-
-function pageReveal() {
-	console.log('[elc]', 'pageReveal');
-	const topDoc = top!.document;
-	topDoc.title = document.title;
-	top!.history.replaceState({}, '', location.href);
-}
-
-function kindAndKey(value: string) {
-	let [kind, key] = value.split(':');
-	if (key === undefined) {
-		key = kind.slice(1);
-		switch (kind[0]) {
-			case '#':
-				kind = 'id';
-				break;
-			case '.':
-				kind = 'class';
-				break;
-			case '@':
-				kind = 'attr';
-				break;
-			case '-':
-				kind = 'style';
-				break;
-			default:
-				console.error(
-					'[crossing]',
-					'syntax error:',
-					value,
-					'is not recognized as a valid specification'
-				);
-		}
-	}
-	return [kind, key];
-}
diff --git a/src/types.ts b/src/types.ts
index 84a1c56..28509a2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,5 +1,17 @@
-export type ElementCrossing = {
-	frameDocument?: Document | undefined;
+export type CrossingStorage = {
+	pseudoAddress(object: object): string;
+	setItem(id: string, object: any): void;
+	getItem(id: string): any | undefined;
+	removeItem(id: string): void;
+	clear(): void;
+};
+
+type ElementCrossing = {
+	addrWeakMap: WeakMap<any, string>;
+	storageMap?: Map<string, any>;
+	frameDocument?: Document;
+	fun: CrossingStorage;
+	iframe?: HTMLIFrameElement;
 };
 
 declare global {
@@ -7,6 +19,7 @@ declare global {
 		__vtbag: {
 			elementCrossing?: ElementCrossing | undefined;
 		};
+		crossingStorage: ElementCrossing['fun'];
 	}
 }
 
diff --git a/src/vanilla.ts b/src/vanilla.ts
index b823220..f93c381 100644
--- a/src/vanilla.ts
+++ b/src/vanilla.ts
@@ -1,46 +1,72 @@
 import { ElementSpec, Spec } from './types';
 
-top!.__vtbag ??= {};
-top!.__vtbag.elementCrossing ??= {};
+const DEBUG = false;
 
+const crossing = top!.__vtbag?.elementCrossing;
 init();
 
 function init() {
-	self.addEventListener("onpageswap" in self ? 'pageswap' : 'pagehide', pageSwap, { once: true });
-	self.addEventListener("onpagereveal" in self ? 'pagereveal' : 'DOMContentLoaded', pageReveal, { once: true });
+	if (crossing?.fun) {
+		if (self === top) {
+			return;
+		}
+		top!.document.title = self.document.title;
+		top!.history.replaceState(self.history.state, '', self.location.href);
+		self.crossingStorage = crossing.fun;
+	}
+
+	self.addEventListener('onpageswap' in self ? 'pageswap' : 'pagehide', pageSwap, { once: true });
+	self.addEventListener('onpagereveal' in self ? 'pagereveal' : 'DOMContentLoaded', pageReveal, {
+		once: true,
+	});
 }
 
 function pageSwap() {
-	console.log('pageSwap');
-	sessionStorage.setItem('@vtbag/element-crossing', JSON.stringify(retrieve()));
+	if (self.crossingStorage) {
+		self.crossingStorage.setItem('@vtbag/element-crossing', retrieve());
+	} else {
+		top!.sessionStorage.setItem('@vtbag/element-crossing', JSON.stringify(retrieve()));
+	}
 }
 
 function pageReveal() {
-	console.log('pageReveal');
-	const values = sessionStorage.getItem('@vtbag/element-crossing');
-	console.log(values);
-	restore(JSON.parse(values ?? "[]"));
+	let values;
+	if (self.crossingStorage) {
+		values = self.crossingStorage.getItem('@vtbag/element-crossing') ?? [];
+	} else {
+		values = JSON.parse(top!.sessionStorage.getItem('@vtbag/element-crossing') ?? '[]');
+	}
+	restore(values);
 }
 
 function retrieve() {
 	const known = new Set<string>();
 	const values: ElementSpec[] = [];
-	self.document
-		.querySelectorAll<HTMLElement>('[data-vtbag-x]')
-		.forEach((element) => {
-			const spec = elementSpec(element);
-			if (spec) {
-				if (known.has(spec.id)) console.error('[crossing]', 'non unique id', spec.id);
-				values.push(spec);
-				known.add(spec.id);
-			}
-		});
+	self.document.querySelectorAll<HTMLElement>('[data-vtbag-x]').forEach((element) => {
+		const spec = elementSpec(element);
+		if (spec) {
+			if (known.has(spec.id)) console.error('[crossing]', 'non unique id', spec.id);
+			values.push(spec);
+			known.add(spec.id);
+		}
+	});
+	DEBUG && console.log('[crossing]', 'retrieve', values);
 	return values;
 }
 
 function elementSpec(element: HTMLElement) {
-	function kindAndKey(value: string) {
+	function kindAndKey(value: string, where: HTMLElement) {
 		let [kind, key] = value.split(':', 2);
+		if (!kind) {
+			console.error(
+				'[crossing]',
+				'syntax error:',
+				value,
+				'is not recognized as a valid specification in',
+				where
+			);
+			return ['<none>', key];
+		}
 		if (key === undefined) {
 			key = kind.slice(1);
 			switch (kind[0]) {
@@ -59,12 +85,16 @@ function elementSpec(element: HTMLElement) {
 				case '~':
 					kind = 'anim';
 					break;
+				case '&':
+					kind = 'elem';
+					if (crossing?.fun) break;
 				default:
 					console.error(
 						'[crossing]',
 						'syntax error:',
 						value,
-						'is not recognized as a valid specification'
+						'is not recognized as a valid specification in',
+						where
 					);
 			}
 		}
@@ -75,9 +105,10 @@ function elementSpec(element: HTMLElement) {
 	const specs: Spec[] = [];
 	element
 		.getAttribute('data-vtbag-x')
-		?.split(' ')
+		?.trim()
+		.split(/\s+/)
 		.forEach((value) => {
-			const [kind, key] = kindAndKey(value);
+			const [kind, key] = kindAndKey(value, element);
 			switch (kind) {
 				case 'id':
 					id = key;
@@ -97,73 +128,112 @@ function elementSpec(element: HTMLElement) {
 				case 'prop':
 					const val = element[key as keyof HTMLElement];
 					const type = typeof val;
-					specs.push({ kind: type === "boolean" ? "bool" : (type === "number" ? "num" : "prop"), key, value: "" + val });
+					specs.push({
+						kind: type === 'boolean' ? 'bool' : type === 'number' ? 'num' : 'prop',
+						key,
+						value: '' + val,
+					});
 					break;
 				case 'anim':
-					const animations = element.getAnimations().filter(a => a instanceof CSSAnimation && a.animationName === key);
+					const animations = element
+						.getAnimations()
+						.filter((a) => a instanceof CSSAnimation && a.animationName === key);
 					if (animations.length > 1) {
-						console.error("[crossing]", `retrieval: animation name ${key} is not unique for`, element);
+						console.error(
+							'[crossing]',
+							`retrieval: animation name ${key} is not unique for`,
+							element
+						);
 					}
 					if (animations.length > 0) {
-						specs.push({ kind, key, value: "" + (animations[0].currentTime ?? 0) });
-					} break;
+						specs.push({ kind, key, value: '' + (animations[0].currentTime ?? 0) });
+					}
+					break;
+				case 'elem':
+					const crossing = top?.__vtbag?.elementCrossing;
+					if (crossing?.fun) {
+						self.crossingStorage.setItem(key, element);
+						specs.push({ kind, key });
+					}
+					break;
 				default:
 					console.error('[crossing]', 'unknown kind', kind);
 					break;
 			}
 		});
-	if (id === undefined) console.error('[crossing]', 'missing id in', element);
+	if (!id) console.error('[crossing]', 'missing id in', element);
 	else return { id, specs };
 }
 
 function restore(values: ElementSpec[]) {
+	DEBUG && console.log('[crossing]', 'restore', values);
 	values.forEach((elementSpec: ElementSpec) => {
-		const element = document.querySelector<HTMLElement>(
-			"#" + elementSpec.id +
-			",[data-vtbag-x*='#" + elementSpec.id +
-			"'],[data-vtbag-x*='id:" + elementSpec.id +
-			"']"
+		let element = document.querySelector<HTMLElement>(
+			'#' +
+				elementSpec.id +
+				",[data-vtbag-x*='#" +
+				elementSpec.id +
+				"'],[data-vtbag-x*='id:" +
+				elementSpec.id +
+				"']"
 		);
-		if (!element) return;
-		elementSpec.specs.forEach((s) => {
-			switch (s.kind) {
-				case 'class':
-					element.classList[s.value === 'true' ? 'add' : 'remove'](s.key);
-					break;
-				case 'style':
-					if (s.key === 'length' || s.key === 'parentRule') {
-						console.error(
-							'[crossing]',
-							'Cannot assign to read-only property',
-							s.key,
-							'in',
-							elementSpec.id
-						);
-					} else {
-						element.style.setProperty(s.key, s.value ?? '');
-					}
-					break;
-				case 'prop':
-					(element as any)[s.key] = s.value;
-					break;
-				case 'bool':
-					(element as any)[s.key] = s.value === "true";
-					break;
-				case 'num':
-					(element as any)[s.key] = parseFloat(s.value ?? "0");
-					break;
-				case 'anim':
-					const animations = element.getAnimations().filter(a => a instanceof CSSAnimation && a.animationName === s.key);
-					if (animations.length > 1) {
-						console.warn("[crossing]", `restore: animation name ${s.key} is not unique for`, element);
-					}
-					animations.forEach(a => a.currentTime = ~~(s.value ?? "0"));
-					element.setAttribute(s.key, s.value ?? '');
-					break;
-				default:
-					console.error('[crossing]', 'unknown kind', s.kind);
-					break;
-			}
-		});
+		if (element) {
+			elementSpec.specs.forEach((s) => {
+				switch (s.kind) {
+					case 'class':
+						element!.classList[s.value === 'true' ? 'add' : 'remove'](s.key);
+						break;
+					case 'style':
+						if (s.key === 'length' || s.key === 'parentRule') {
+							console.error(
+								'[crossing]',
+								'Cannot assign to read-only property',
+								s.key,
+								'in',
+								elementSpec.id
+							);
+						} else {
+							element!.style.setProperty(s.key, s.value ?? '');
+						}
+						break;
+					case 'prop':
+						(element as any)[s.key] = s.value;
+						break;
+					case 'bool':
+						(element as any)[s.key] = s.value === 'true';
+						break;
+					case 'num':
+						(element as any)[s.key] = parseFloat(s.value ?? '0');
+						break;
+					case 'anim':
+						const animations = element!
+							.getAnimations()
+							.filter((a) => a instanceof CSSAnimation && a.animationName === s.key);
+						if (animations.length > 1) {
+							console.warn(
+								'[crossing]',
+								`restore: animation name ${s.key} is not unique for`,
+								element
+							);
+						}
+						animations.forEach((a) => (a.currentTime = ~~(s.value ?? '0')));
+						element!.setAttribute(s.key, s.value ?? '');
+						break;
+					case 'elem':
+						const crossing = top?.__vtbag?.elementCrossing;
+						if (crossing?.fun) {
+							const replacement = self.crossingStorage.getItem(s.key) as HTMLElement;
+							if (replacement) {
+								element!.replaceWith(replacement);
+								element = replacement;
+							}
+						}
+						break;
+					default:
+						console.error('[crossing]', 'unknown kind', s.kind);
+						break;
+				}
+			});
+		}
 	});
 }