Merge pull request #990 from vector-im/bwindels/updates-docs

Document how updates work, reorganize docs

FAQ.md

@@ -36,4 +36,4 @@ Published builds can be found at https://github.com/vector-im/hydrogen-web/relea
 
 ## I want to embed Hydrogen in my website, how should I do that?
 
-Hydrogen aims to be usable as an SDK, and while it is still early days, you can find some documentation how to do that in [SDK.md](SDK.md).
+Hydrogen aims to be usable as an SDK, and while it is still early days, you can find some documentation how to do that in [SDK.md](doc/SDK.md).

README.md

@@ -43,4 +43,4 @@ PS: You need nodejs, running yarn on top of any other js platform is not support
 
 # FAQ
 
-Some frequently asked questions are answered [here](doc/FAQ.md).
+Some frequently asked questions are answered [here](FAQ.md).

doc/GOAL.md

@@ -1,8 +0,0 @@
-goal:
-
-write client that works on lumia 950 phone, so I can use matrix on my phone.
-
-try approach offline to indexeddb. go low-memory, and test the performance of storing every event individually in indexeddb.
-
-try to use little bandwidth, mainly by being an offline application and storing all requested data in indexeddb.
-be as functional as possible while offline

doc/SKINNING.md

@@ -1,22 +0,0 @@
-# Replacing javascript files
-
-Any source file can be replaced at build time by mapping the path in a JSON file passed in to the build command, e.g. `yarn build --override-imports customizations.json`. The file should be written like so:
-
-```json
-{
-    "src/platform/web/ui/session/room/timeline/TextMessageView.js": "src/platform/web/ui/session/room/timeline/MyTextMessageView.js"
-}
-```
-The paths are relative to the location of the mapping file, but the mapping file should be in a parent directory of the files you want to replace.
-
-You should see a "replacing x with y" line (twice actually, for the normal and legacy build).
-
-# Injecting CSS
-
-You can override the location of the main css file with the `--override-css <file>` option to the build script. The default is `src/platform/web/ui/css/main.css`, which you probably want to import from your custom css file like so:
-
-```css
-@import url('src/platform/web/ui/css/main.css');
-
-/* additions */
-```

doc/TODO.md

@@ -1,77 +0,0 @@
-# Minimal thing to get working
-
- - DONE: finish summary store
- - DONE: move "sdk" bits over to "matrix" directory
- - DONE: add eventemitter
- - DONE: make sync work
- - DONE: store summaries
- - DONE: setup editorconfig
- - DONE: setup linting (also in editor)
- - DONE: store timeline
- - DONE: store state
- - DONE: make summary work better (name and joined/inviteCount doesn't seem to work well)
- - DONE: timeline doesn't seem to recover it's key well upon loading, the query in load seems to never yield an event in the persister
- - DONE: map DOMException to something better
- 	- it's pretty opaque now when something idb related fails. DOMException has these fields:
- 		code: 0
-		message: "Key already exists in the object store."
-		name: "ConstraintError"
- - DONE: emit events so we can start showing something on the screen maybe?
- - DONE: move session._rooms over to Map, so we can iterate over it, ...
- - DONE: build a very basic interface with
- 	- DONE: a start/stop sync button
- 	- DONE: a room list sorted alphabetically
- - DONE: do some preprocessing on sync response which can then be used by persister, summary, timeline
- - DONE: support timeline
- 	- DONE: clicking on a room list, you see messages (userId -> body)
- - DONE: style minimal UI
- - DONE: implement gap filling and fragments (see FRAGMENTS.md)
- - DONE: allow collection items (especially tiles) to self-update
- - improve fragmentidcomparer::add
- - DONE: better UI
- - fix MappedMap update mechanism
- - see if in BaseObservableMap we need to change ...params
- - DONE: put sync button and status label inside SessionView
- - fix some errors:
-    - find out if `(this._emitCollectionUpdate)(this)` is different than `this._emitCollectionUpdate(this)` 
-    - got "database tried to mutate when not allowed" or something error as well
-    - find out why when RoomPersister.(\_createGapEntry/\_createEventEntry) we remove .buffer the transaction fails (good), but upon fixing and refreshing is missing a message! syncToken should not be saved, so why isn't this again in the sync response and now the txn does succeed?
- - DONE: take access token out of IDB? this way it can be stored in a more secure thing for non-web clients, together wit encryption key for olm sessions ... ? like macos keychain, gnome keyring, ... maybe using https://www.npmjs.com/package/keytar
- - DONE: experiment with using just a normal array with 2 numbers for sortkeys, to work in Edge as well.
- - DONE: send messages
- - DONE: fill gaps with call to /messages
-
- - DONE: build script
-    - DONE: take dev index.html, run some dom modifications to change script tag with `parse5`.
-    - DONE: create js bundle, rollup
-    - DONE: create css bundle, postcss, probably just need postcss-import for now, but good to have more options
-    - DONE: put all in /target
-    - have option to run it locally to test
-
- - deploy script
-    - upload /target to github pages
-
- - DONE: offline available
-    - both offline mechanisms have (filelist, version) as input for their template:
-        - create appcache manifest with (index.html, brawl.js, brawl.css) and print version number in it
-        - create service worker wit file list to cache (at top const files = "%%FILES_ARRAY%%", version = "%%VERSION%%")
-        - write web manifest
- - DONE: delete and clear sessions from picker
- - option to close current session and go back to picker
- 
- - accept invite
- - member list
- - e2e encryption
- - sync retry strategy
-    - instead of stopping sync on fetch error, show spinner and status and have auto retry strategy
-
- - create room
- - join room
- - leave room
- - unread rooms, badge count, sort rooms by activity
-
- - DONE: create sync filter
- - DONE: lazy loading members
- - decide denormalized data in summary vs reading from multiple stores PER room on load
- - allow Room/Summary class to be subclassed and store additional data?
- - store account data, support read markers

doc/api.md

@@ -1,90 +0,0 @@
-Session
-	properties:
-		rooms -> Rooms
-
-# storage
-Storage
-	key...() -> KeyRange
-	start...Txn() -> Transaction
-Transaction
-	store(name) -> ObjectStore
-	finish()
-	rollback()
-ObjectStore : QueryTarget
-	index(name)
-Index : QueryTarget
-
- 
-Rooms: EventEmitter, Iterator<RoomSummary>
-	get(id) -> RoomSummary ?
-InternalRoom: EventEmitter
-	applySync(roomResponse, membership, txn)
-		- this method updates the room summary
-		- persists the room summary
-		- persists room state & timeline with RoomPersister
-		- updates the OpenRoom if present
-
-
-		applyAndPersistSync(roomResponse, membership, txn) {
-			this._summary.applySync(roomResponse, membership);
-			this._summary.persist(txn);
-			this._roomPersister.persist(roomResponse, membership, txn);
-			if (this._openRoom) {
-				this._openRoom.applySync(roomResponse);
-			}
-		}
-
-RoomPersister
-	RoomPersister	(persists timeline and room state)
-	RoomSummary		(persists room summary)
-RoomSummary : EventEmitter
-	methods:
-		async open()
-		id
-		name
-		lastMessage
-		unreadCount
-		mentionCount
-		isEncrypted
-		isDirectMessage
-		membership
-
-		should this have a custom reducer for custom fields?
-
-	events
-		propChange(fieldName)
-
-OpenRoom : EventEmitter
-	properties:
-		timeline
-	events:
-
-
-RoomState: EventEmitter
-	[room_id, event_type, state_key] -> [sort_key, event]
-Timeline: EventEmitter
-	// should have a cache of recently lookup sender members?
-	// can we disambiguate members like this?
-	methods:
-		lastEvents(amount)
-		firstEvents(amount)
-		eventsAfter(sortKey, amount)
-		eventsBefore(sortKey, amount)
-	events:
-		eventsApppended
-
-RoomMembers : EventEmitter, Iterator
-	// no order, but need to be able to get all members somehow, needs to map to a ReactiveMap or something
-	events:
-		added(ids, values)
-		removed(ids, values)
-		changed(id, fieldName)
-RoomMember: EventEmitter
-	properties:
-		id
-		name
-		powerLevel
-		membership
-		avatar
-	events:
-		propChange(fieldName)

doc/architecture/updates.md

@@ -0,0 +1,58 @@
+# Updates
+
+How updates flow from the model to the view model to the UI.
+
+## EventEmitter, single values
+
+When interested in updates from a single object, chances are it inherits from `EventEmitter` and it supports a `change` event.
+
+`ViewModel` by default follows this pattern, but it can be overwritten, see Collections below.
+
+### Parameters
+
+Often a `parameters` or `params` argument is passed with the name of the field who's value has now changed. This parameter is currently only sometimes used, e.g. when it is too complicated or costly to check every possible field. An example of this is `TilesListView.onUpdate` to see if the `shape` property of a tile changed and hence the view needs to be recreated. Other than that, bindings in the web UI just reevaluate all bindings when receiving an update. This is a soft convention that could probably be more standardized, and it's not always clear what to pass (e.g. when multiple fields are being updated).
+
+Another reason to keep this convention around is that if one day we decide to add support for a different platform with a different UI, it may not be feasible to reevaluate all data-bindings in the UI for a given view model when receiving an update.
+
+## Collections
+
+As an optimization, Hydrogen uses a pattern to let updates flow over an observable collection where this makes sense. There is an `update` event for this in both `ObservableMap` and `ObservableList`. This prevents having to listen for updates on each individual item in large collections. The `update` event uses the same `params` argument as explained above.
+
+Some values like `BaseRoom` emit both with a `change` event on the event emitter and also over the collection. This way consumers can use what fits best for their case: the left panel can listen for updates on the room over the collection to power the room list, and the room view model can listen to the event emitter to get updates from the current room only.
+
+### MappedMap and mapping models to `ViewModel`s
+
+This can get a little complicated when using `MappedMap`, e.g. when mapping a model from `matrix/`
+to a view model in `domain/`. Often, view models will want to emit updates _spontanously_,
+e.g. without a prior update being sent from the lower-lying model. An example would be to change the value of a field after the view has called a method on the view model.
+To support this pattern while having updates still flow over the collection requires some extra work;
+`ViewModel` has a `emitChange` option which you can pass in to override
+what `ViewModel.emitChange` does (by default it emits the `change` event on the view model).
+`MappedMap` passes a callback to emit an update over the collection to the mapper function.
+You can pass this callback as the `emitChange` option and updates will now flow over the collection.
+
+`MappedMap` also accepts an updater function, which you can use to make the view model respond to updates
+from the lower-lying model.
+
+Here is an example:
+
+```ts
+const viewModels = someCollection.mapValues(
+	    (model, emitChange) => new SomeViewModel(this.childOptions({
+	        model,
+	        // will make ViewModel.emitChange go over
+	        // the collection rather than emit a "change" event
+	        emitChange,
+	    })),
+	    // an update came in from the model, let the vm know
+	    (vm: SomeViewModel) => vm.onUpdate(),
+	);
+```
+
+### `ListView` & the `parentProvidesUpdates` flag.
+
+`ObservableList` is always rendered in the UI using `ListView`. When receiving an update over the collection, it will find the child view for the given index and call `update(params)` on it. Views will typically need to be told whether they should listen to the `change` event in their view model or rather wait for their `update()` method to be called by their parent view, `ListView`. That's why the `mount(args)` method on a view supports a `parentProvidesUpdates` flag. If `true`, the view should not subscribe to its view model, but rather updates the DOM when its `update()` method is called. Also see `BaseUpdateView` and `TemplateView` for how this is implemented in the child view.
+
+## `ObservableValue`
+
+When some method wants to return an object that can be updated, often an `ObservableValue` is used rather than an `EventEmitter`. It's not 100% clear cut when to use the former or the latter, but `ObservableValue` is often used when the returned value in it's entirety will change rather than just a property on it.  `ObservableValue` also has some nice facilities like lazy evaluation when subscribed to and the `waitFor` method to work with promises.

doc/viewhierarchy.md

@@ -1,21 +0,0 @@
-view hierarchy:
-```
-    BrawlView
-        SwitchView
-            SessionView
-                SyncStatusBar
-                ListView(left-panel)
-                    RoomTile
-                SwitchView
-                    RoomPlaceholderView
-                    RoomView
-                        MiddlePanel
-                            ListView(timeline)
-                                event tiles (see ui/session/room/timeline/)
-                            ComposerView
-                        RightPanel
-            SessionPickView
-                ListView
-                    SessionPickerItemView
-            LoginView
-```