mystiq/hydrogen-web
Archived
4
1
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #637 from vector-im/bwindels/timeline-readme

Browse source 
add basic readme for updates in the timeline
This commit is contained in:
Bruno Windels 2022-01-14 19:16:25 +01:00 committed by GitHub
commit 000c8b27c3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
src/matrix/room/timeline/README.md Normal file
View file

@ -0,0 +1,22 @@
# Timeline
## Nomenclature
- Entry: an element that can be part of the timeline. This is either an event or a gap. When they are part of the timeline, entries are sorted by their fragmentId first, then their event index.
- Tile: a view model around one or more entries. A tile will be rendered by one view.
## How are timeline updates propagated?
Most timeline updates are caused by either sync or a gap fill. These happen in `Room` and will call `Timeline.addEntries` for now entries and `Timeline.replaceEntries` for entries that where previously known to Hydrogen and received some kind of update. They may or may not have been loaded into the timeline already. Examples of what causes an update is: a relation was added to the target event, the event was redacted, the event was decrypted where it couldn't be before, ...
Also events that haven't been sent yet are shown in the timeline, always below the remote messages. These updates are triggered in `SendQueue` and passed through the `pendingEvents` observable list.
`Timeline` exposes an observable list with all (sorted) entries under the `entries` property. Additions, updates and removals are emitted over this collection, once subscribed.
### Context entries
Some messages in the timeline require another message to be able to display themselves. The only example of this currently is replies. When an entry is added to the timeline, it's `contextEventId` property will be checked. If it returns an id, we'll try to get the matching entry, either from the loaded messages, storage or the /context endpoint from the server.
Note that /context entries are not stored because [currently it is not possible](https://github.com/vector-im/hydrogen-web/pull/491) to detect overlap between timeline fragments created by sync and fragments created by /context, and storing events presumes it will be in a fragment. This means they can't be updated by the relation writer, as it assumes an entry is in storage. Hence for relation and redaction support, we reuse the local echo infrastructure (`entry.addLocalRelation()`) used already for pending events.
When the context entry is updated through `replaceEntries`, an update event will also be emitted for every entry in the timeline that uses the updated entry as context. An example is when a replied-to message is redacted, the reply entry will also emit an update.