v6 – Big changes

[Ayc0]

Problem

There are a few APIs I wanted to change for quite some time.

1. For Make useMediaRange() support strict typing #63, I would like to be able to have functions that are better typed end-to-end.
2. See Add createMediaRanges() #184
3. See Remove the props as and ...props in Only #186

Proposal

New API

Introduce a system via createMediaRanges:

import { createMediaRanges, DEFAULT_MEDIA_RANGES } from '@blocz/react-responsive';

const { useMediaRange: useMediaRangeCustomized, Only: OnlyCustomized } = createMediaRanges({
  ...DEFAULT_MEDIA_RANGES,
  pxRange: [263, 863, { unit: "px" }],
  emRange: [20, 40, { unit: "em" }],
})

^ As you can see here: createMediaRanges would behave a bit like MediaRangesProvider but without any differences between additionalMediaRanges & mediaRanges. Instead it’d fully behave like mediaRanges aka override everything, and if you want to use the default ones, you’ll have to import them.

Stronger types

In the previous example here, pxRange can statically analyzed. So we can more easily do useMediaRangeCustomized('pxRange') to check that the it matches a valid media query (as it's fully linked to the keys defined in createMediaRanges)

To come back to #63, Most use cases are single uses for useMediaRange(). So having to do useMediaRange(['md']) wouldn't be practical; and yes would make it harder to memoize properly in React.

So we can use a recursive generic typing using a string that would check for spaces, and can do checks like useMediaRangeCustomized('md pxRange invalid') and see that md & pxRange are valid, but not invalid and throw a type error.

Only changes

As mentioned in #186, Only needs to drop as and ...props. Instead we'll have to render the as as a child, which is a breaking change.

Existing APIs

To make it easy to use, we should still exposed useMediaRange & Only, and make them connect to MediaRangesProvider as now, but also deprecate MediaRangesProvider.
And in addition, add createMediaRanges that wouldn't be listening to MediaRangesProvider.

And existing useMediaRange + Only will continue using the old types (with the exception of as and ...props).

useMediaQuery won't be impacted otherwise

Migration plan

1. introduce in 5.1.0 createMediaRanges with the new types, and deprecate MediaRangesProvider. Only generated by createMediaRanges would already drop support for as and ...props, but not the top-level one.
2. in 6.0.0 remove MediaRangesProvider. And update Only & useMediaRange to only be able to support default ranges (as custom ranges, atm only customizable via MediaRangesProvider will be removed), and drop as & ...props in Only