Start rewriting docs towards queries

[tstirrat15]

Fixes #118

Motivation

This is one of the tasks before a v2 master release.

Discussion

• What is the behavior of queries plus child components (i.e. not a child function, but rather child JSX)? Must all queries match, or is it at least one query matches? This bit seems to indicate that it's some as opposed to every.
• Waiting to see whether query will exist alongside queries

[edorivai]

What is the behavior of queries plus child components (i.e. not a child function, but rather child JSX)?

Good question, didn't even think about this actually 🤔. Now that you mention it, the same goes for the render prop... @mjackson have you got an opinion about this?

[gribnoysup]

Maybe my two cents on the topic will help a little as I am responsible for the queries PR 😊

First of all, I tried to preserve the previous behaviour of the render method as much as possible following the discussion in #69

What is the behaviour of queries plus child components ...

This was the "biggest" change in the PR in my opinion.

With query it was pretty straightforward what to do there for the render: if it matches, render children, if it's not, skip rendering. Now when the matches are an object, I decided to go with render even if one matches, as otherwise, it seems pointless to have queries in the first place.

You also can have a case where none of them will match at the same time ever (imagine mixing {min,max}-width for example), so nothing will be rendered ever. I thought that those cases could be really frustrating for some library users.

Hope this clarifies the decision behind some instead of every

Now, with this approach, there is still an issue. If we are rendering children for some cases, how to make children aware of the reason? We can't send those props to a component when it is a DOM element, this will cause React to print nasty warnings (and for a good reason). So instead I decided to pass matches as a prop to children component, but only if it is NOT a DOM element

Waiting to see whether query will exist alongside queries

Per an initial comment in the issue #69 (comment) @mjackson suggested "to release a 2.x that removes the <Media query> prop and uses <Media queries> instead"

Hope that helps!

[edorivai]

@mjackson suggested "to release a 2.x that removes the prop and uses instead"

Yeah, I'm aware of this, and when I first read it, I thought it made a lot of sense. However, I came to realize that - at least for my own code bases - this would require quite a lot of refactoring if I'd want to upgrade to v2, without really getting any benefit since most of the time I'm only specifying a single query.

I would actually expect the single-query case to be the most common one, by a significant margin. So given both the smooth transition path, as well as a convenience API for the single-query case, I thought it'd be worth it to consider leaving the query prop alongside queries.

[tstirrat15]

Meaning we'd need a PR against the work in #72 to preserve that behavior, yeah?

[edorivai]

@tstirrat15 Yeah, that's right

[tstirrat15]

@edorivai shall I update this towards #123, or do you want to get that merged first?

[edorivai]

I've just merged #123 into next, and plan to merge next into master soon. So yeah, I'd say you can start updating towards that.

[tstirrat15]

@edorivai have another look. I added a section to Basic Usage with query as an alternative, added a section about the salient differences between the two props, and moved the Render Props documentation to be children of the separate query and queries documentation. It's maybe a little redundant, but I think it's comprehensive.

[edorivai]

👍 Love it!