Implement throttle and debounce as event actions

[masenf]

Generic client side throttling and debounce for events.

Used just like .stop_propagation and .prevent_default, so applicable to all event handler or event spec objects.

Due to how events are handled, there isn't currently a way to apply these to only a single event in the chain. If multiple event handlers are specified and any of them have debounce or throttle, then it will apply to all of the other events as well.

If the same function is throttled or debounced at the same limit/delay by multiple event triggers, these will all apply in the same domain. If different limit or delay is used, then they will be debounced or throttled separately.

Sample Code

import time


import reflex as rx


class State(rx.State):
    """The app state."""
    _t_events: int = 0
    _d_events: int = 0
    last_t_event: str
    last_d_event: str
    slider_value: list[int] = 30

    def handle_mouse_move_t(self):
        self._t_events += 1
        self.last_t_event = f"throttle moved: {self._t_events} {time.time()}"
        print(self.last_t_event)

    def handle_mouse_move_db(self):
        self._d_events += 1
        self.last_d_event = f"debounce moved: {self._d_events} {time.time()}"
        print(self.last_d_event)

    def handle_slider_change(self, value):
        self.slider_value = value[0]


def index() -> rx.Component:
    return rx.hstack(
        rx.box(
            rx.vstack(
                rx.heading("Throttle"),
                rx.box(height="50vh"),
                State.last_t_event,
                align="center",
                padding_top="10vh",
            ),
            on_mouse_move=lambda: State.handle_mouse_move_t.throttle(500),
            height="85vh",
            width="50vw",
            background="linear-gradient(#e66465, #9198e5)"
        ),
        rx.box(
            rx.vstack(
                rx.heading("Debounce"),
                rx.box(height="50vh"),
                State.last_d_event,
                align="center",
                padding_top="10vh",
            ),
            on_mouse_move=State.handle_mouse_move_db.debounce(500),
            height="85vh",
            width="50vw",
            background="linear-gradient(#9198e5, #e66465)"
        ),
    ), rx.cond(
        State.is_hydrated,
        rx.vstack(
            rx.heading(State.slider_value),
            rx.slider(
                default_value=[State.slider_value],
                min=0,
                max=100,
                on_change=State.handle_slider_change.debounce(50),
            ),
            align="center",
        )
    )


app = rx.App()
app.add_page(index)

Screen.Recording.2024-04-15.at.16.25.55.mov

Edit 2024-04-16: added a debounced slider example. Note it's important to wrap is the is_hydrated cond, otherwise the default_value after refreshing will be the initial value, not the last value.

[Lendemor]

Nice, the UX will be much better for high fire-rate events !

Could we add a test when the event handler is a lambda? I expect the behaviour to be the same, but might as well be sure.

[Lendemor]

I shoud have been more specific in the test I wanted, but since lambda are used to pass pre-set parameter, when we do, do we use

lambda value: EventActionState.on_change_throttle_with_args(value, "arg1").throttle(200).stop_propagation

or

(lambda value: EventActionState.on_change_throttle_with_args(value, "arg1")).throttle(200).stop_propagation

?
Though maybe it's more important to have this particular example in the docs than the tests.

[Lendemor]

closes #1482 #2872

[picklelo]

This is a much needed feature, let me think a bit more on the final API but I like it

[picklelo]

works great with my color picker