API Proposal: User Event `scroll` function

[mdjastrzebski]

@siepra is working User Event scroll API design, the code is quite advanced, so it's high time that we have a solid API with nice DX for that feature. There is no RTL's User Event API for scrolling, so we need to come up with our own. As a base for discussion, I have prepare an initial proposal.

User Event scroll API

Base case

// vertical scroll
user.scrollTo(element, { y: targetPos })

// horizontal scroll:
user.scrollTo(element, { x: targetPos })

Note: the function is named scrollTo instead of scroll to remove ambiguity whether this is target value or relative value. Coincidently this is also the name of imperative handle for scrolling in RN.

This will emit a sequence of onScrollBeginDrag, onScroll (x N), onScrollEndDrag.

By default, the first scroll will start from (0, 0) and will emit default of 5 onScroll intermediate steps between initial position and target position. Subsequent scrolls will start from where the last scroll (using User Event) ended.

Intermediate steps

Explicit steps

Alternatively, you can pass exact steps that will be called as an array. First element is the initial position, and all other elements indicate subsequent steps. The number of steps will be equal to the length of the array.

user.scrollTo(element, { y: [0, 10, 20, 30] })

Number of steps (alternative approach)

You can customize the intermediate steps by passing number of steps and/or ininitial position:

user.scrollTo(element, { y: targetPos, steps: 10 })
user.scrollTo(element, { y: targetPos, fromY: initialPos })
user.scrollTo(element, { y: targetPos, fromY: initialPos, steps: 10 })

We probably should pick only one of the above. Based on my surveys with CK devs, the first one seems to be preferred.

Momentum scroll

Momentum scroll happens after initial sequence of onScrollBeginDrag, onScroll (x N), onScrollEndDrag when scroll view has some velocity (momentum) after user lifts the finger up. This will result in calling onMomentumScrollBegin, onScroll (x N), onMomentumScrollEnd.

By default scrollBy will only invoke drag scroll without momentum part. User can activate momentum scroll passing momentumY or momentumX variables:

// vertical
user.scrollTo({ momentumY: targetPos })

// horizontal
user.scrollTo({ momentumX: targetPos })

This can be linked with previous options:

// Drag scroll from initial position to targetPos1, then momentum scroll to targetPos2
user.scrollTo({ y: targetPos1, momentumY: targetPos2 })

// Pass explicit steps and/or momentum steps
user.scrollTo({ y: [0, 10, 20], momentumY: [30, 40] })

// Control the number of drag steps using `steps`, and momentum steps using `momentumSteps` (alternative intermediate steps approach)
user.scrollTo({ y: targetPos1, momentumY: targetPos2, steps: 5, momentumSteps: 4 })

If the user did not pass drag scroll position, then distance from last position, or default (0, 0), to target position will be divided equally between drag scroll and momentum scroll.

Please share your comments on all things involved, naming of function and options, ways of conveying ideas like intermediate steps, etc, etc. Feel free to challenge this design, propose alternatives, etc. The API is very flexible at this stage, changing it later will probably require breaking changes, etc.

Links

• Our wiki page about experiment Scroll View events
• Current implementation PR
• RN ScrollView docs
• Cypress scrollTo docs
• MDN's scrollTo docs
• Detox scroll/scrollTo docs

Specific questions:

1. Should the API be named scrollTo or scroll?
2. What should be default number of scroll steps, if not specified by user. Similar for momentum steps?
3. Should we support indicating number of steps using steps param, y: [0, 10, 20] array or both? Or other perhaps?
4. How should we expose momentum scroll concept: momentumY params, momentum: boolean param, user.momentumScrollTo() function, or other perhaps?
5. Should RNTL remember the last scroll position and start next scroll from there? Or should we always start from explicit position or (0,0) if not provided?

CC: @pierrezimmermannbam @AugustinLF @MattAgn @thymikee @siepra

[flexbox]

1. scrollTo is a better name, crystal clear on the intention.
2. whatever works 😅
3. array or both? I would say only arrays. If you take another example from react-query for the v3 to v4 migration they introduced a breaking change to support only arrays Query Keys (and Mutation Keys) need to be an Array. I have the feeling supporting both is prone to errors.
4. without digging into the API, I can understand the concept behind momentumY
5. that's tricky but I would say following what happens on the device is the way. I would choose "remember the last scroll position" because that's what happens when users doom scroll, change the app, back into the previous app.

[mdjastrzebski]

@flexbox re 5: that would be limited to single test case. i.e. scroll position would be remembered between two subsequent user.scrollTo(element) calls. In a separate test case, element will have a different object identity, and hence will start again from (0, 0).

In real RN app, scroll position is most probably a native state (yoga might be involved as well?), you do not manage that through props like you would with a managed TextInput content. Since there is no "native" part in RNTL we would keep track of last scroll position for each scrollable element.

[pierrezimmermannbam]

1. Yes I agree scrollTo is better

2. I find the notion of step a bit confusing here. It looks like it serves two purposes: emitting an onScroll event and also a separate scroll because you can provide momentum for each step (user would stop scrolling between each step). Those two things should be decoupled and I believe we should see steps as independent scrolls, i.e. the two following syntaxes would be strictly equivalent:

user.scrollTo({ y: [0, 10], momentumY: [30, 40] })

user.scrollTo({ y: [0], momentumY: [30] })
user.scrollTo({ y: [10], momentumY: [40] })

That leaves up the question of how often should onScroll be called. From RN docs, onScroll Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. This isn't very precise so we can't be precise either but I think we should emit events every x ms (not sure about the value, it could change if the scrollEventThrottle prop is defined), making an assumption on the scroll speed to determine how long the scroll would last (scroll speed could be configurable eventually)

Now if the steps are equivalent to multiple scrollTo calls I'm not sure it's worth supporting them. I don't think it will be used that much and it does not make things much simpler imo. So maybe we should stick with a simpler API for now?

3. If we do steps I would also say only array syntax

4. I like the proposal, there is just something that's unclear to me, if I do

user.scrollTo({ y: [30], momentumY: [30] })

Does it scroll to 30 with 30 momentum or does it scroll to 60 (30+30 momentum)? If it's the first should we throw if momentum is greater than y? Maybe this behavior could be described through ts-doc

5. It would be better to remember current scroll position but since elements can't be measured I don't know if it makes a huge difference. Also if scrollview is scrolled programmatically (through a ref) current position will be false because scrollview methods are mocked and don't do anything

[siepra]

1. I agree with all the others. scrollTo is surely better.

2. I think usually there're less momentum events than scroll events. Also I think it's important to emit multiple scroll events so one can test against multiple method calls, but maybe it's not that important how many of them will occur. I'd say e.g. 5 regular and 3 momentum scroll events is rational.

re: It looks like it serves two purposes: emitting an onScroll event and also a separate scroll because you can provide momentum for each step (user would stop scrolling between each step). : Momentum will always follow the current direction (it prolongs the gesture) so my original intention was to give the possibility to specify it's value as an addition to the x or y value.

re: Now if the steps are equivalent to multiple scrollTo calls I'm not sure it's worth supporting them : Not exactly. scrollTo emits a combination of events while those intermediate steps are scroll events only.

3. I like the array approach, but it gives the possibility to do "strange" combinations like changing direction mid-gesture (it may not be that important though).

4. See the "re:" above.

5. I agree with @flexbox

[mdjastrzebski]

@pierrezimmermannbam thanks for comments.
re 2: I think I've might written the momentum part in slightly confusing way. So to clarify my intent, momentum scroll will always happen after drag scroll:

user.scrollTo({ x: [0, 5, 10], momentumX: [20, 25, 30] });

Will emit:

scrollBeingDrag 0
scroll 5
scrollEndDrag 10 (experimantally there is on `scroll` event equal to `scrollEndDrag`)
momentumScrollBegin 20
scroll 25
scroll 30
momentumScrollEnd 30 (experimentally last `scroll` event of momentum part is equalt to `momentumScrollEnd`

So that would be equivalent to:

user.scrollTo({ x: [0, 5, 10] });
user.scrollTo({ momentumX: [20, 25, 30] });

[pierrezimmermannbam]

Oh I see, I didn't understand that, that makes sense. In your example if the drag ends at 10 then shouldn't the momentum begin at 10?

I'm still a bit afraid that this API is too complex and not easily understandable. I'm not convinced that steps bring value and imo they make the API way more complicated and also allow for incoherent values for the momentum like [0, 10, 0]. I can't find use cases where I'd use steps but maybe I haven't encountered some before, what cases can you think of?

For now I think I'd prefer a more simpler API that would look like this:

user.scrollTo({ x: 5, momentumX: 5});

That would emit

scrollBeingDrag 0
scroll 5
scrollEndDrag 5 (experimantally there is on `scroll` event equal to `scrollEndDrag`)
momentumScrollBegin 5
scroll 10
momentumScrollEnd 10

You'd need to have the previous position of the scrollview to know in which direction the momentum is though. It's not great either though because it's still a bit unclear wether you scroll to 5 having included the momentum scroll or to 5 + 5.

[mdjastrzebski]

@pierrezimmermannbam re momentum scroll:

• All of the values both x and momentumX represent the final scroll value, they are not relative/additive. This is the reason they are named scrollTo not scrollBy. I think this approach makes reasoning about tests much easier. E.g. user.scrollTo({ x: 5, momentumX: 10 }); will do drag scroll till 5 and then momentum scroll till 10 (not 15).
• When supplying as single number, e.g. scrollTo({ x: 100 }) only specify that final scroll value, there will be intermediate scroll events but you ask UE to calculate these for you. By default there will be e.g. 5 of these intermediate steps.
• When supplying the array of numbers, e.g. scrollTo({ x: [0, 10, 20] }) you have complete control about intermediate scroll events, these will be 0 (scrollBeginDrag), 10 (scroll), 20 (scrollEndDrag). These are for the case when you want to have control about intermediate values because e.g. you might want to do some assertions, etc.