trrack / trrackjs Goto Github PK

Hi, I have been using the library and it is working well! However I was initially confused that the docs home page says the docs are for "Trrack v2" but the NPM package linked from the README is @trrack/core which has the latest version of v1.3.0. I was unsure if I was looking at the wrong docs/package.

With further investigation it seems that v1 vs. v2 refers to @visdesignlab/trrack vs. @trrack/core. A note about this would make it more clear.

Steps to reproduce

1. Clone repo
2. Run yarn dev:all
3. Check console output

Observed behavior

[...rack-example] ERROR in ./apps/react-trrack-example/src/app/store/trrack.ts:46:7
[...rack-example] TS2345: Argument of type '(add: number) => { type: string; payload: number; meta: { hasSideEffects: boolean; }; }' is not assignable to parameter of type 'TrrackActionFunction<"increment-counter", string, any, number> | StateChangeFunction<number, number>'.
[...rack-example]   Type '(add: number) => { type: string; payload: number; meta: { hasSideEffects: boolean; }; }' is not assignable to type 'TrrackActionFunction<"increment-counter", string, any, number>'.
[...rack-example]     Property 'undo' is missing in type '{ type: string; payload: number; meta: { hasSideEffects: boolean; }; }' but required in type '{ do?: { payload: number; type: "increment-counter"; } | undefined; undo: { payload: any; type: string; }; }'.
[...rack-example]     44 |     const incrementCounter = reg.register(
[...rack-example]     45 |       'increment-counter',
[...rack-example]   > 46 |       (add: number) => {
[...rack-example]        |       ^^^^^^^^^^^^^^^^^^
[...rack-example]     47 |         setCounter((c) => c + add);
[...rack-example]     48 |         return {
[...rack-example]     49 |           type: 'decrement-counter',
[...rack-example] 
[...rack-example] ERROR in ./apps/react-trrack-example/src/app/store/trrack.ts:60:7
[...rack-example] TS2345: Argument of type '(sub: number) => { type: string; payload: number; meta: { hasSideEffects: boolean; }; }' is not assignable to parameter of type 'StateChangeFunction<number, number> | TrrackActionFunction<"decrement-counter", string, any, number>'.
[...rack-example]   Type '(sub: number) => { type: string; payload: number; meta: { hasSideEffects: boolean; }; }' is not assignable to type 'StateChangeFunction<number, number>'.
[...rack-example]     Type '{ type: string; payload: number; meta: { hasSideEffects: boolean; }; }' is not assignable to type 'number'.
[...rack-example]     58 |     const decrementCounter = reg.register(
[...rack-example]     59 |       'decrement-counter',
[...rack-example]   > 60 |       (sub: number) => {
[...rack-example]        |       ^^^^^^^^^^^^^^^^^^
[...rack-example]     61 |         setCounter((c) => c - sub);
[...rack-example]     62 |         return {
[...rack-example]     63 |           type: 'increment-counter',
[...rack-example] 
[...rack-example] Found 2 errors in 339 ms.

The action functions for incrementCounter and decrementCounter are probably not up-to-date with the most recent typings.

Expected behavior

The examples should compile without errors.

What
It would be useful to be able to conveniently determine if currentChange was triggered by node traversal (undo/redo/click on trrackViz) vs a user action causing a new node to be added to the track tree. This could be added as an argument in the currentChange callback, or property on the trrack object returned by initializeTrrack.

Why
My current approach to handling provenance with vue/pinia is to subscribe to changes on the pinia store then call the relevant prov.apply(...) function to update the trrack state. Then of prov.currentChange is triggered. Now we get to the branching logic.

• Case 1: If we have a new node, we know this was triggered from a store update, so we don't want to make any changes to the store.
• Case 2: If we move to an existing node, that means we must update the pinia store to update the ui.

Workaround
Right now, I have a working solution:

const prov = initializeTrrack(...);
const nodeIds = new Set<string>([prov.root.id]);
prov.currentChange(() => {
    const provNodeId = prov.current.id;
    if (nodeIds.has(prov.current.id)) {
        // update pinia state based on trrack state
    } else {
        // do nothing
    }
    nodeIds.add(provNodeId);
});

So far, this appears to be working. I'm not sure how this will work with URL state sharing — it may require some updates, i.e. adding all of the state node ids on initial load probably.

Currently, Trrack documentation is on a NextJS page with markdowns.

We can switch to any other static site generator if it has documentation-specific features like search.

Currently each diff node has all patches starting from last checkpoint.

Change to use minimal diff for the current node. We can collect the diffs as we go and apply.

https://github.com/datavisyn/reprovisyn/issues/477#issuecomment-1211715320

Maybe using lz-string package.

Options:

• Mobx-like reaction implementation from Trrack 1.0 (see alloc/wana)
• Custom event listeners backed by RxJS (see deanrad/omnibus-rxjs)
• Trrack graph is managed by redux-toolkit, leverage the middleware listener API

Should allow for the addition of custom chunking logic, traversal logic, etc.

The TrrackJS docs page has usage examples and some conceptual explanations. We need an API + Types reference auto-generated from the code using typedoc or something similar.

@JackWilb @bbollen23 will appreciate any input on this. I have used typedoc earlier, and most of the code has JSDoc-style comments.

Checkpoint nodes should be created for every n node. We must determine the best way to calculate N — parameterize or calculate. And do performance testing for different choices (see #61).

We have the types and the metadata attributes on the nodes. We don't expose a function to add/remove/set these.

Metadata is the ONLY change allowed in an already created node. To keep the provenance of metadata changes, the metadata attribute should have the following data structure:

type MetadataObject<T> = {
	timestamp: string;
	value: T
}

type Metadata<T> = Array<MetadataObject<T>>

The API should provide the following:

• Add new metadata to the node. Only take the metadata as input, and generate timestamps internally.
• Get available metadata types
• Get the latest metadata of a type
• Get all metadata of a type
• Get all metadata

Implement a similar API for artifacts. Artifacts can be used to store arbitrary objects/object URLs like screenshots, etc.

Depends on implementing #37

Function which takes a search term and metadata keys to search and returns a list of all nodes or node IDs whose keys match the search terms. This will be paired with a search bar and updates to trrackvis in a separate issue there.

Groups and annotations should also be searchable.

The documentation page should have a

• university of utah
• visualization design lab
• nsf logo

on each page in the footer.

The about page should also mention SCI and Kahlert School of Computing.

Consider adding an undo-as-delete default feature to cull the unnecessary branches.

https://idl.cs.washington.edu/files/2008-GraphicalHistories-InfoVis

We can limit the delete interaction to hide rather than remove it from the history. This can help reduce the clutter. Refer to the paper above for some techniques and considerations for implementing such a feature.

TODO:

• create a plan of action on how undo-as-delete will work.
• changes to the API
• defaults

The user who made a specific change should be trracked. Easiest way to implement this is probably to have the implementer provide a username as a string argument to the action call.

Set up a benchmarking suite for calculating storage size for user studies (probably from reVisit).

A script to traverse the provenance and update the state for each node according to different frequencies of checkpoints (#65) and using the new diff mechanism (#64).

If nodes have 'ephemeral': true in the metadata, they should collapse together in a group

This should be a function that takes a DOM node to screenshot and arguments related to when to screenshot. A config should be provided to choose which actions trigger screenshots. Either default include all or exclude all and provide a list of action keys which are exceptions to the overall rule. Once ephemeral nodes are added, they should not be included in the count before next screenshot.

Example here https://github.com/datavisyn/sightline/blob/mweigl/145_trrack-vis/src/store/store.ts. The untrrackedAppSlice is created with a normal createSlice call, instead of the createTrrackableSlice. It's state still appears on the node, and is still set when traversing back to this node. This creates problems, as our app doesn't expect traversing to affect this part of the store.