aberdeen 0.2.2 → 0.2.4

package/src/prediction.ts

@@ -0,0 +1,117 @@
+import {withEmitHandler} from 'aberdeen'
+
+type ObsCollection = any
+type Patch = Map<ObsCollection, Map<any, [any, any]>>;
+
+
+function recordPatch(func: () => void): Patch {
+	const recordingPatch = new Map()
+	withEmitHandler(function(index, newData, oldData) {
+		addToPatch(recordingPatch, this, index, newData, oldData)
+	}, func)
+	return recordingPatch
+}
+
+function addToPatch(patch: Patch, collection: ObsCollection, index: any, newData: any, oldData: any) {
+	let collectionMap = patch.get(collection)
+	if (!collectionMap) {
+		collectionMap = new Map()
+		patch.set(collection, collectionMap)
+	}
+	let prev = collectionMap.get(index)
+	if (prev) oldData = prev[1]
+	if (newData === oldData) collectionMap.delete(index)
+	else collectionMap.set(index, [newData, oldData])
+}
+
+function emitPatch(patch: Patch) {
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			collection.emitChange(index, newData, oldData)
+		}
+	}
+}
+
+function mergePatch(target: Patch, source: Patch, reverse: boolean = false) {
+	for(let [collection, collectionMap] of source) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			addToPatch(target, collection, index, reverse ? oldData : newData, reverse ? newData : oldData)
+		}
+	}
+}
+
+function silentlyApplyPatch(patch: Patch, force: boolean = false): boolean {
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			let actualData = collection.rawGet(index)
+			if (actualData !== oldData) {
+				if (force) setTimeout(() => { throw new Error(`Applying invalid patch: data ${actualData} is unequal to expected old data ${oldData} for index ${index}`)}, 0)
+				else return false
+			}
+		}
+	}
+	for(let [collection, collectionMap] of patch) {
+		for(let [index, [newData, oldData]] of collectionMap) {
+			collection.rawSet(index, newData)
+		}
+	}
+	return true
+}
+
+
+const appliedPredictions: Array<Patch> = []
+
+/**
+ * Run the provided function, while treating all changes to Observables as predictions,
+ * meaning they will be reverted when changes come back from the server (or some other
+ * async source).
+ * @param predictFunc The function to run. It will generally modify some Observables
+ * 	to immediately reflect state (as closely as possible) that we expect the server
+ *  to communicate back to us later on.
+ * @returns A `Patch` object. Don't modify it. This is only meant to be passed to `applyCanon`.
+ */
+export function applyPrediction(predictFunc: () => void): Patch {
+	let patch = recordPatch(predictFunc)
+	appliedPredictions.push(patch)
+	emitPatch(patch)
+	return patch
+}
+
+/**
+ * Temporarily revert all outstanding predictions, optionally run the provided function
+ * (which will generally make authoritative changes to the data based on a server response),
+ * and then attempt to reapply the predictions on top of the new canonical state, dropping 
+ * any predictions that can no longer be applied cleanly (the data has been modified) or
+ * that were specified in `dropPredictions`.
+ * 
+ * All of this is done such that redraws are only triggered if the overall effect is an
+ * actual change to an `Observable`.
+ * @param canonFunc The function to run without any predictions applied. This will typically
+ *  make authoritative changes to the data, based on a server response.
+ * @param dropPredictions An optional list of predictions (as returned by `applyPrediction`)
+ *  to undo. Typically, when a server response for a certain request is being handled,
+ *  you'd want to drop the prediction that was done for that request.
+ */
+export function applyCanon(canonFunc?: (() => void), dropPredictions: Array<Patch> = []) {
+	
+	let resultPatch = new Map()
+	for(let prediction of appliedPredictions) mergePatch(resultPatch, prediction, true)
+	silentlyApplyPatch(resultPatch, true)
+
+	for(let prediction of dropPredictions) {
+		let pos = appliedPredictions.indexOf(prediction)
+		if (pos >= 0) appliedPredictions.splice(pos, 1)
+	}
+	if (canonFunc) mergePatch(resultPatch, recordPatch(canonFunc))
+
+	for(let idx=0; idx<appliedPredictions.length; idx++) {
+		if (silentlyApplyPatch(appliedPredictions[idx])) {
+			mergePatch(resultPatch, appliedPredictions[idx])
+		} else {
+			appliedPredictions.splice(idx, 1)
+			idx--
+		}
+	}
+
+	emitPatch(resultPatch)
+}

package/src/route.ts

@@ -0,0 +1,131 @@
+import {Store, observe, immediateObserve, inhibitEffects} from 'aberdeen'
+
+/**
+ * A `Store` object that holds the following keys:
+ * - `path`: The current path of the URL split into components. For instance `/` or `/users/123/feed`. Updates will be reflected in the URL and will *push* a new entry to the browser history.
+ * - `p`: Array containing the path segments. For instance `[]` or `['users', 123, 'feed']`. Updates will be reflected in the URL and will *push* a new entry to the browser history. Also, the values of `p` and `path` will be synced.
+ * - `search`: An observable object containing search parameters (a split up query string). For instance `{order: "date", title: "something"}` or just `{}`. Updates will be reflected in the URL, modifying the current history state. 
+ * - `hash`: The document hash part of the URL. For instance `"#section-title"`. It can also be an empty string. Updates will be reflected in the URL, modifying the current history state.
+ * - `state`: The browser history *state* object for the current page. Creating or removing top-level keys will cause *pushing* a new entry to the browser history.
+ * 
+ * The following key may also be written to `route` but will be immediately and silently removed: 
+ * - `mode`: As described above, this library takes a best guess about whether pushing an item to the browser history makes sense or not. When `mode` is...
+ * 	  	- `"push"`: Force creation of a new browser history entry. 
+ * 	  	- `"replace"`: Update the current history entry, even when updates to other keys would normally cause a *push*.
+ * 		- `"back"`: Unwind the history (like repeatedly pressing the *back* button) until we find a page that matches the given `path`, `search` and top-level `state` keys, and then *replace* that state by the full given state.
+ */
+export const route = new Store()
+
+// Contains url (path+search) and state for all history entries for this session, with the current
+// entry on top. It is used for `mode: "back"`, to know how many entries to go back.
+let stack: Array<{url: string, state: object}> = []
+
+// Keep track of the initial history length, so we'll always know how long our `stack` should be.
+const initialHistoryLength = history.length;
+
+// Keep a copy of the last known history state, so we can tell if the user changed one of its
+// top-level keys, so we can decide between push/replace when `mode` is not set.
+let prevHistoryState: any
+
+// Reflect changes to the browser URL (back/forward navigation) in the `route` and `stack`.
+function handleLocationUpdate(event?: PopStateEvent) {
+	const search: any= {}
+	for(let [k, v] of new URLSearchParams(location.search)) {
+		search[k] = v
+	}
+	prevHistoryState = event ? (event.state || {}) : {}
+	stack.length = Math.max(1, history.length - initialHistoryLength + 1)
+	stack[stack.length-1] = {url: location.pathname + location.search, state: prevHistoryState}
+	route.set({
+		path: location.pathname,
+		p: location.pathname.slice(1).split('/'),
+		search: search,
+		hash: location.hash,
+		state: prevHistoryState,
+	})
+}
+handleLocationUpdate()
+window.addEventListener("popstate", handleLocationUpdate);
+
+// These immediate-mode observers will rewrite the data in `route` to its canonical form.
+// We want to to this immediately, so that user-code running immediately after a user-code
+// initiated `set` will see the canonical form (instead of doing a rerender shortly after,
+// or crashing due to non-canonical data).
+function updatePath(): void {
+	let path = route.get('path')
+	if (path == null && route.peek('p')) {
+		return updateP();
+	} 
+	path = ''+path
+	if (!path.startsWith('/')) path = '/'+path
+	route.set('path', path)
+	route.set('p', path.slice(1).split('/'))
+}
+immediateObserve(updatePath)
+
+function updateP(): void {
+	const p = route.get('p')
+	console.log('imm p', p)
+	if (p == null && route.peek('path')) {
+		return updatePath()
+	}
+	if (!(p instanceof Array)) {
+		console.error(`aberdeen route: 'p' must be a non-empty array, not ${JSON.stringify(p)}`)
+		route.set('p', ['']) // This will cause a recursive call this observer.
+	} else if (p.length == 0) {
+		route.set('p', ['']) // This will cause a recursive call this observer.
+	} else {
+		route.set('path', '/' + p.join('/'))
+	}
+}
+immediateObserve(updateP)
+
+immediateObserve(() => {
+	if (route.getType('search') !== 'object') route.set('search', {})
+})
+
+immediateObserve(() => {
+	if (route.getType('state') !== 'object') route.set('state', {})
+})
+
+immediateObserve(() => {
+	let hash = ''+(route.get('hash') || '')
+	if (hash && !hash.startsWith('#')) hash = '#'+hash
+	route.set('hash', hash)
+})
+
+// This deferred-mode observer will update the URL and history based on `route` changes.
+observe(() => {
+	// Get and delete mode without triggering anything.
+	const mode = route.get('mode')
+	if (mode) inhibitEffects(() => route.delete('mode'))
+	const state = route.get('state')
+	
+	// Construct the URL.
+	const path = route.get('path')
+	const search = new URLSearchParams(route.get('search')).toString()
+	const url = (search ? path+'?'+search : path) + route.get('hash')
+
+	// Change browser state, according to `mode`.
+	if (mode === 'back') {
+		let goDelta = 0
+		while(stack.length > 1) {
+			const item = stack[stack.length-1]
+			if (item.url === url && JSON.stringify(Object.keys(state||{})) === JSON.stringify(Object.keys(item.state||{}))) break // Found it!
+			goDelta--
+			stack.pop()
+		}
+		if (goDelta) history.go(goDelta)
+		// We'll replace the state async, to give the history.go the time to take affect first.
+		setTimeout(() => history.replaceState(state, '', url), 0)
+		stack[stack.length-1] = {url,state}
+	} else if (mode === 'push' || (!mode && (location.pathname !== path || JSON.stringify(Object.keys(state||{})) !== JSON.stringify(Object.keys(prevHistoryState||{}))))) {
+		history.pushState(state, '', url)
+		stack.push({url,state})
+	} else {
+		history.replaceState(state, '', url)
+		stack[stack.length-1] = {url,state}
+	}
+	prevHistoryState = state
+})
+

package/src/transitions.ts

@@ -0,0 +1,73 @@
+import {scheduleDomReader, scheduleDomWriter} from 'aberdeen'
+
+const FADE_TIME = 400
+const GROW_SHRINK_TRANSITION = `margin ${FADE_TIME}ms ease-out, transform ${FADE_TIME}ms ease-out`
+
+function getGrowShrinkProps(el: HTMLElement) {
+	const parentStyle: any = el.parentElement ? getComputedStyle(el.parentElement) : {}
+	const isHorizontal = parentStyle.display === 'flex' && (parentStyle.flexDirection||'').startsWith('row')
+	return isHorizontal ?
+		{marginLeft: `-${el.offsetWidth/2}px`, marginRight: `-${el.offsetWidth/2}px`, transform: "scaleX(0)"} :
+		{marginBottom: `-${el.offsetHeight/2}px`, marginTop: `-${el.offsetHeight/2}px`, transform: "scaleY(0)"}
+
+}
+
+/** Do a grow transition for the given element. This is meant to be used as a
+* handler for the `create` property.
+*
+* @param el The element to transition.
+*
+* The transition doesn't look great for table elements, and may have problems
+* for other specific cases as well.
+*/
+export function grow(el: HTMLElement): void {
+	// This timeout is to await all other elements having been added to the Dom
+	scheduleDomReader(() => {
+		// Make the element size 0 using transforms and negative margins.
+		// This causes a browser layout, as we're querying el.offset<>.
+		let props = getGrowShrinkProps(el)
+		
+		// The timeout is in order to batch all reads and then all writes when there
+		// are multiple simultaneous grow transitions.
+		scheduleDomWriter(() => {
+			Object.assign(el.style, props)
+			
+			// This timeout is to combine multiple transitions into a single browser layout
+			scheduleDomReader(() => {
+				// Make sure the layouting has been performed, to cause transitions to trigger
+				el.offsetHeight
+				scheduleDomWriter(() => {
+					// Do the transitions
+					el.style.transition = GROW_SHRINK_TRANSITION
+					for(let prop in props) el.style[prop as any] = ""
+					setTimeout(() => {
+						// Reset the element to a clean state
+						el.style.transition = ""
+					}, FADE_TIME)
+				})
+			})
+		})
+	})
+}
+
+/** Do a shrink transition for the given element, and remove it from the DOM
+* afterwards. This is meant to be used as a handler for the `destroy` property.
+*
+* @param el The element to transition and remove.
+*
+* The transition doesn't look great for table elements, and may have problems
+* for other specific cases as well.
+*/
+export function shrink(el: HTMLElement): void {
+	scheduleDomReader(() => {
+		const props = getGrowShrinkProps(el)
+		// The timeout is in order to batch all reads and then all writes when there
+		// are multiple simultaneous shrink transitions.
+		scheduleDomWriter(() => {
+			el.style.transition = GROW_SHRINK_TRANSITION
+			Object.assign(el.style, props)
+			
+			setTimeout(() => el.remove(), FADE_TIME)
+		})
+	})
+}