Refetch interval UI control

[david-crespo]

Goes with #1178. We don't want to do refetching haphazardly and opaquely; we want to give the user control.

Figma

Implementation thoughts

We are probably using the picker to get a value for RQ refetchInterval. No other approach comes to mind. In order to make this value available to the useQuery call is, either there needs to be a hook, or we could go the traditional route and use local state and a Listbox with an onChange. This is simple enough that it should probably just be a hook that wraps everything up. On the other hand I had some trouble with the date range picker hook returning an element that caused me to refactor it in #1225 into a hook for the state + a normal component. The normal component is definitely more testable.

const { refetchInterval, refetchIntervalPicker } = useRefetchIntervalPicker()
const { data, dataUpdatedAt } = useApiQuery('organizationList', {}, { refetchInterval })

return (
  <>
    <DataUpdatedAt ts={dataUpdatedAt} />
    {refetchIntervalPicker}
  </>
)

useQuery returns a dataUpdatedAt timestamp we can use for the Updated 15 seconds ago bit. The hook needs to return false if refetch is set to Off because that's what RQ wants.

Note that the hook can't handle rendering the timestamp because that depends on the useQuery. We could however write a new hook useRefetchApiQuery() 😁 that combines both — it would keep the same calling interface as useApiQuery(), the only difference would be that it would also return the picker to render. But we tend to regret making combined things like this without trying the separated version first.

[david-crespo]

@benjaminleonard @paryhin now that I tried implementing it in #1247, I have some thoughts on the refetch button. The control should let the user:

1. Trigger a refetch manually
2. Toggle auto mode
3. Set the interval
4. See when the data was last fetched
5. See whether we're in auto mode
6. See what the auto interval is

I assume the 🔄 button is meant to handle 1. 2 and 3 are covered by the menu. 4 is covered. But I don't think 5 and 6 are good enough. You can open the list to see what's selected, but you can't see at a glance. In practice I think 5 is more important than 6, so it would be ok if you could see up front that you're in auto refetch mode but have to hover or click to see what the interval is.

[paryhin]

I propose two options to solve this issue. Personal preference is the top one, as in that case, we don't introduce any new behavior and patterns. The bottom one takes slightly less space and offers better grouping of elements.

[paryhin]

It would be nice to add a loading state for this control as well, like rotating spinner, if manual refreshing takes more than a second.

[david-crespo]

It probably won't take more than a second, but we could set a minimum amount of time for the loading spinner to appear so it doesn't flash too quickly. We could also use a more subtle loading state so the flash is less jarring.

I like the top one better too. I still think it's not clear enough what the "Off" or "10s" is referring to. On GCP they have a 1 minute interval badge that's sort of ambiguous, and it has a tooltip explaining that it refers to the granularity of the data, not to a refresh interval (I don't think they have auto refresh). So I'm afraid that unless we call out "refresh every..." somewhat explicitly, it will not be clear what it means.

[david-crespo]

I'm realizing now that the above can be read as an argument for option 2, because the refresh button inside the picker makes clear that it's about refreshing. My problem with 2 is that the hierarchy is a little confusing. It's not clear enough that the refresh button is a button, because it's inside another thing that is also basically a button. I wonder if it would work better if it looked more like a button group, though the middle button would not actually be a button, so that's kind of weird.

[paryhin]

A simple solution to clarify that “off” is refresh interval can be a headline in the dropdown:

Button group is a valid option, but there is an issue of slight inconsistency with date picker behavior:

A third option can be adding manual refresh as an option in the dropdown itself, with an obvious drawback of extra click:

[david-crespo]

I like the button group. What do you mean by inconsistency with the date picker?

I don't like option 3. GCP does something similar, but it's in a more typical hamburger menu. I don't like it there either, but having it as a listbox option feels confusing because it's the only one that does something immediately. I like the button options.

[paryhin]

Inconsistency is that calendar button brings the dropdown, but refresh button refreshes charts, and arrows bring the dropdown. Not a huge deal, but still.

Overall, button group works for me.

[david-crespo]

Heh guess our users will have to stay alert.

[zephraph]

I'm surprised about having a dropdown that controls the refresh interval. I could see having the button group to control options like manual or auto, but the interval length seems like it should be something we control. I don't see what the value of changing that would be. If someone doesn't want see a refresh for a bit they may be trying to take a screenshot or something in which case they can either not enable it or disable it if it is enabled.

[zephraph]

Broadly for tables I think we should only have three options:

1. Never refresh
2. Refresh in place (e.g. refresh the rows I see, but that's it)
3. Refresh all (e.g. do a new query, I'm okay if data shuffles around)

The frequency of refresh should likely be tuned by use from a performance perspective. We should communicate the interval length to users through a label, tooltip, etc.

[david-crespo]

The more granular stuff is aimed at metrics pages. I can definitely see the argument there for not having options for intervals — maybe on or off is enough. It seems like GCP doesn't do it at all. At least, I couldn't find it. Would be interesting to compare AWS and Azure and others.

I agree normal tables should be very limited in refetch functionality, possibly with no interval at all, only manual (which simplifies the UX a lot).

2 would require bulk fetch by ID endpoints. I don't see that coming any time soon.

[david-crespo]

@paryhin I'm picking this back up this week. The more I think about it, the more I agree with @zephraph's suggestion that we don't even really need interval options. This doesn't cut down that much the list of functions from my previous comment — the only one it gets rid of entirely is 3, though it does also guarantee that 2 and 5 can be done together.

1. Trigger a refetch manually (button)
2. Toggle auto mode (checkbox)
3. Set the interval
4. See when the data was last fetched (message)
5. See whether we're in auto mode (checkbox)
6. See what the auto interval is (tooltip probably)

This was the version of the control I liked best.

What do you think about a version of that but with a checkbox for refetching, and maybe we just say Refetch every 10 seconds in a tooltip? To me the hard part is figuring out how to label the checkbox.

----------------
| 🔄 | [ ] auto |
----------------

Could be worse.

[paryhin]

Updated version based on our discussion. Figma link for now.