feat: Add breakpoints helper tools

Author: Jimco

packages/react/src/hooks/useMediaQuery.ts

@@ -36,6 +36,8 @@ export function useMediaQuery(
         initializeWithValue = true,
     }: UseMediaQueryOptions = {},
 ): boolean {
+    query = query?.replace(/^@media( ?)/m, '');
+
     const getMatches = (query: string): boolean => {
         if (IS_SERVER) {
             return defaultValue;

packages/react/src/index.ts

@@ -1 +1,2 @@
 export * from './hooks';
+export * from './utils';

packages/react/src/types/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Remove properties `K` from `T`.
+ * Distributive for union types.
+ */
+declare type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+
+/**
+ * Like `T & U`, but using the value types from `U` where their properties overlap.
+ */
+declare type Overwrite<T, U> = DistributiveOmit<T, keyof U> & U;
+
+/**
+ * Generate a set of string literal types with the given default record `T` and
+ * override record `U`.
+ *
+ * If the property value was `true`, the property key will be added to the
+ * string union.
+ */
+declare type OverridableStringUnion<T extends string | number, U = any> = GenerateStringUnion<
+    Overwrite<Record<T, true>, U>
+>;

packages/react/src/utils/create-breakpoints.ts

@@ -0,0 +1,189 @@
+export interface BreakpointOverrides {}
+
+export type Breakpoint = OverridableStringUnion<
+    'xs' | 'sm' | 'md' | 'lg' | 'xl',
+    BreakpointOverrides
+>;
+
+export interface Breakpoints {
+    keys: Breakpoint[];
+
+    /**
+     * Each breakpoint (a key) matches with a fixed screen width (a value).
+     * @default {
+     *    // extra-small
+     *    xs: 0,
+     *    // small
+     *    sm: 576,
+     *    // medium
+     *    md: 768,
+     *    // large
+     *    lg: 992,
+     *    // extra-large
+     *    xl: 1200,
+     * }
+     */
+    values: { [key in Breakpoint]: number };
+
+    /**
+     * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+     * @returns A media query string ready to be used with most styling solutions,
+     * which matches screen widths greater than the screen size given by the breakpoint
+     * key (inclusive).
+     */
+    up: (key: Breakpoint | number) => string;
+
+    /**
+     * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+     * @returns A media query string ready to be used with most styling solutions, which matches screen widths less than the screen size given by the breakpoint key (exclusive).
+     */
+    down: (key: Breakpoint | number) => string;
+
+    /**
+     * @param start - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+     * @param end - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+     * @returns A media query string ready to be used with most styling solutions,
+     * which matches screen widths greater than the screen size given by the breakpoint
+     * key in the first argument (inclusive) and less than the screen size given by the
+     * breakpoint key in the second argument (exclusive).
+     */
+    between: (start: Breakpoint | number, end: Breakpoint | number) => string;
+
+    /**
+     * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+     * @returns A media query string ready to be used with most styling solutions,
+     * which matches screen widths starting from the screen size given by the breakpoint
+     * key (inclusive) and stopping at the screen size given by the next breakpoint
+     * key (exclusive).
+     */
+    only: (key: Breakpoint) => string;
+
+    /**
+     * @param key - A breakpoint key (`xs`, `sm`, etc.).
+     * @returns A media query string ready to be used with most styling solutions,
+     * which matches screen widths stopping at the screen size given by the breakpoint
+     * key (exclusive) and starting at the screen size given by the next breakpoint
+     * key (inclusive).
+     */
+    not: (key: Breakpoint) => string;
+
+    /**
+     * The unit used for the breakpoint's values.
+     * @default 'px'
+     */
+    unit?: string | undefined;
+}
+
+export interface BreakpointsOptions extends Partial<Breakpoints> {
+    /**
+     * The increment divided by 100 used to implement exclusive breakpoints.
+     * For example, `step: 5` means that `down(500)` will result in `'(max-width: 499.95px)'`.
+     * @default 5
+     */
+    step?: number | undefined;
+
+    /**
+     * The unit used for the breakpoint's values.
+     * @default 'px'
+     */
+    unit?: string | undefined;
+}
+
+// Sorted ASC by size. That's important.
+// It can't be configured as it's used statically for propTypes.
+export const breakpointKeys = ['xs', 'sm', 'md', 'lg', 'xl'];
+
+const sortBreakpointsValues = (values: Breakpoints['values']) => {
+    const breakpointsAsArray = Object.keys(values).map(key => ({
+        key,
+        val: values[key],
+    })) || [];
+
+    // Sort in ascending order
+    breakpointsAsArray.sort(
+        (breakpoint1, breakpoint2) => breakpoint1.val - breakpoint2.val,
+    );
+
+    return breakpointsAsArray.reduce((acc, obj) => {
+        return {
+            ...acc,
+            [obj.key]: obj.val,
+        };
+    }, {});
+};
+
+// Keep in mind that @media is inclusive by the CSS specification.
+export default function createBreakpoints(breakpoints: BreakpointsOptions): Breakpoints {
+    const {
+        // The breakpoint **start** at this value.
+        // For instance with the first breakpoint xs: [xs, sm).
+        values = {
+            xs: 0,
+            // phone
+            sm: 576,
+            // tablet
+            md: 768,
+            // small laptop
+            lg: 992,
+            // desktop / large screen
+            xl: 1200,
+        },
+        unit = 'px',
+        step = 5,
+        ...other
+    } = breakpoints;
+    const sortedValues = sortBreakpointsValues(values);
+    const keys = Object.keys(sortedValues);
+
+    function up(key: Breakpoint | number) {
+        const value = typeof values[key] === 'number' ? values[key] : key;
+        return `@media (min-width:${value}${unit})`;
+    }
+
+    function down(key: Breakpoint | number) {
+        const value = typeof values[key] === 'number' ? values[key] : key;
+        return `@media (max-width:${value - step / 100}${unit})`;
+    }
+
+    function between(start: Breakpoint | number, end: Breakpoint | number) {
+        const endIndex = keys.indexOf(end);
+        return (
+            `@media (min-width:${typeof values[start] === 'number' ? values[start] : start}${unit}) and `
+            + `(max-width:${(endIndex !== -1 && typeof values[keys[endIndex]] === 'number' ? values[keys[endIndex]] : end) - step / 100}${unit})`
+        );
+    }
+
+    function only(key: Breakpoint) {
+        if (keys.indexOf(key) + 1 < keys.length) {
+            return between(key, keys[keys.indexOf(key) + 1]);
+        }
+        return up(key);
+    }
+
+    function not(key: Breakpoint) {
+        // handle first and last key separately, for better readability
+        const keyIndex = keys.indexOf(key);
+        if (keyIndex === 0) {
+            return up(keys[1]);
+        }
+        if (keyIndex === keys.length - 1) {
+            return down(keys[keyIndex]);
+        }
+        return between(key, keys[keys.indexOf(key) + 1]).replace(
+            '@media',
+            '@media not all and',
+        );
+    }
+
+    return {
+        keys,
+        values: sortedValues,
+        up,
+        down,
+        between,
+        only,
+        not,
+        unit,
+        ...other,
+    };
+}

packages/react/src/utils/index.ts

@@ -0,0 +1 @@
+export { default as createBreakpoints } from './create-breakpoints';