When you have an imperative API, where to put configuration is a no-brainer. Just stuff it right into the call!
$(div).toggleClass('active').fadeIn(500);
$(div).toggleClass('active').fadeIn(500);
When you move to a declarative API, many imperative callsites turn into one.
You used to call $(div).toggleClass('active') in ten places, but now you setActive(!active) instead, and have one place that says:
<div className={active ? 'active' : null} />
Cool.
You used to call $(div).toggleClass('active') in ten places, but now you setActive(!active) instead, and have one place that says:
<div className={active ? 'active' : null} />
Cool.
This helps separate the intent (“I want to change whether it’s active”) from implementation details (“when it’s active, we want this particular UI output”). Yay for separation of concerns.
When you move to a declarative API, how do you know when to stop? It’s tempting to just keep moving things into it.
<FadeIn delay={500}>
<div className={active ? 'active' : null} />
</FadeIn>
<FadeIn delay={500}>
<div className={active ? 'active' : null} />
</FadeIn>
This is sort of what the early version of Suspense looked like.
<Suspense timeoutMs={500} fallback={<Spinner />}>
<Thing />
</Suspense>
It seemed “declarative” that Suspense would specify how long it’s willing to “pause the world” before showing the fallback.
<Suspense timeoutMs={500} fallback={<Spinner />}>
<Thing />
</Suspense>
It seemed “declarative” that Suspense would specify how long it’s willing to “pause the world” before showing the fallback.
Over months of internal testing, we learned a `timeoutMs` prop was a wrong API (thankfully never shipped to open source!) It was a source of endless confusion at FB.
Why? It was wrong to have timeout on “what” side. How long a user is comfortable waiting for a screen transition depends on where and why it *originated*.
If a button that started the transition has some inline indicator, it’s ok to “pause the world”. But maybe there isn’t one.
If a button that started the transition has some inline indicator, it’s ok to “pause the world”. But maybe there isn’t one.
We learned this lesson for Suspense. But it’s more general, and you need to pay attention to it when designing APIs with a declarative boundary. Different pieces of information may belong on different sides of the imperative/declarative “wall”.
If you have a declarative system and keep piling hacks to distinguish different cases that reduce to the same state, maybe you’re losing information somewhere along the way. Maybe capturing it earlier and making it first-class would help.
Relevant for routing too.
