New: Add cascading option

Author: ejhammond

.eslintrc.js

@@ -3,5 +3,10 @@ module.exports = {
   globals: {
     __DEV__: 'readonly',
   },
-  rules: { '@typescript-eslint/ban-ts-ignore': 'off' },
+  rules: {
+    '@typescript-eslint/ban-ts-ignore': 'off',
+    // we've abstracted our expects into a help fn
+    // so we don't necessarily need an `expect` inside of each test block
+    'jest/expect-expect': 'off',
+  },
 };

README.md

@@ -146,8 +146,8 @@ import Button from './components/Button';
 
 <Button
   buttonText="Default text"
-  sm={{ buttonText: 'Small screen text', buttonSize: 'mini' }}
-  lg={{ buttonText: 'Large screen text', buttonSize: 'large' }}
+  sm={{ buttonText: 'Small screen text', buttonSize: 'large' }}
+  lg={{ buttonText: 'Large screen text', buttonSize: 'normal' }}
 />;
 ```
 
@@ -158,6 +158,86 @@ import Button from './components/Button';
 [TypeScript](https://github.com/tripphamm/react-responsive-system/tree/master/examples/typescript)
 [Gatsby](https://github.com/tripphamm/react-responsive-system/tree/master/examples/gatsby)
 
+## Cascading
+
+By default, Responsive System overrides do not cascade, which is to say: if you add an override for screen class `X`, those overrides will only be applied when the user's browser/device matches screen class `X`. But in some cases, you might want to apply overrides on `X` and also anything larger/smaller than `X`.
+
+This is where `cascadeMode` comes in.
+
+Let's take an example. We'll assume that we have 4 screen classes, "xs", "sm", "md", and "lg" and that we have a `Button` component that can be either `normal` or `large`. On most screen sizes, we want our button to be `normal` size, but on `xs` screens (like mobile phones) we want to make the button nice and big so that it's easier to tap.
+
+There are 2 ways that you can do this with the default configuration of Responsive System:
+
+```jsx
+<Button
+  // default is "normal"
+  buttonSize="normal"
+  // override on xs screens
+  xs={{ buttonSize: 'large' }}
+/>
+```
+
+This approach is called "desktop-first" because the default values pertain to larger screens, and we provide overrides for smaller screens.
+
+We could also write this in a "mobile-first" way like this:
+
+```jsx
+<Button
+  // default to "large"
+  buttonSize="large"
+  // override on sm, md, and lg screens
+  sm={{ buttonSize: 'normal' }}
+  md={{ buttonSize: 'normal' }}
+  lg={{ buttonSize: 'normal' }}
+/>
+```
+
+In this particular case, the "desktop-first" approach is shorter and easier to understand, but sometimes the reverse will be true. Using the default `cascadeMode` ("no-cascade") allows you to choose which approach works best on a case-by-case basis. You pick your default values and then apply overrides for any screen sizes that need special treatment.
+
+For folks who find value in having a consistent "desktop-first" or "mobile-first" approach throughout their apps, we also provide `cascadeMode = "desktop-first"` and `cascadeMode = "mobile-first"`. In these modes, you always provide default values for either your largest screen class ("desktop-first") or your smallest ("mobile-first") and your overrides will _cascade_.
+
+Going back to our example, if we had used `cascadeMode = "desktop-first"` we would still write:
+
+```jsx
+<Button
+  // desktop-first default value
+  buttonSize="normal"
+  // override on xs screens AND anything smaller
+  xs={{ buttonSize: 'large' }}
+/>
+```
+
+The desktop-first cascade would automatically add our overrides on any screen classes smaller that `xs`, but no such screen classes exist, so the cascade doesn't come into play here.
+
+On the other hand, if we had used `cascadeMode = "mobile-first"`, we could take advantage of the mobile-first cascade:
+
+```jsx
+<Button
+  // mobile-first default value
+  buttonSize="large"
+  // override on sm AND anything larger
+  sm={{ buttonSize: 'normal' }}
+/>
+```
+
+The mobile-first cascade says "apply these overrides on _this_ screen class _and_ any larger screen classes too".
+
+Put another way:
+
+- "no-cascade" - `sm` overrides apply only on `sm` screens
+- "desktop-first" - `sm` overrides apply on `sm` and `xs` screens
+- "mobile-first" = `sm` overrides apply on `sm`, `md`, and `lg`
+
+If you'd like to enable desktop/mobile-first cascading, you can pass the `cascadeMode` option to `createResponsiveSystem`.
+
+```js
+export const { ScreenClassProvider, responsive } = createResponsiveSystem({
+  breakpoints,
+  defaultScreenClass: 'lg',
+  cascadeMode: 'mobile-first', // or "desktop-first"
+});
+```
+
 ## Custom Merge Function
 
 By default, Responsive System will apply any screen-size-specific overrides right on top of your base props, but sometimes you need more control over how your overrides are applied.

examples/typescript/index.tsx

@@ -21,37 +21,26 @@ const App = () => {
       <FunctionComponentWithHOC
         someColor="#000000"
         someText="overridden"
-        xs={{ someColor: 'rebeccapurple', someText: 'xs' }}
         sm={{ someColor: 'palevioletred', someText: 'sm' }}
         md={{ someColor: 'brown', someText: 'md' }}
-        lg={{ someColor: 'green', someText: 'lg' }}
       />
       <ForwardRefComponentWithHOC
         ref={forwardRefCompRef}
         someColor="#000000"
         someText="overridden"
-        xs={{ someColor: 'rebeccapurple', someText: 'xs' }}
         sm={{ someColor: 'palevioletred', someText: 'sm' }}
         md={{ someColor: 'brown', someText: 'md' }}
-        lg={{ someColor: 'green', someText: 'lg' }}
       />
       <ClassComponentWithHOC
         ref={classCompRef}
         someColor="#000000"
         someText="overridden"
-        xs={{ someColor: 'rebeccapurple', someText: 'xs' }}
         sm={{ someColor: 'palevioletred', someText: 'sm' }}
         md={{ someColor: 'brown', someText: 'md' }}
-        lg={{ someColor: 'green', someText: 'lg' }}
       />
       <HostComponentWithHOC
         ref={hostCompRef}
         style={{ color: 'white', height: 100, width: 100, backgroundColor: '#000000' }}
-        xs={(baseProps) => ({
-          ...baseProps,
-          style: { ...baseProps.style, backgroundColor: 'rebeccapurple' },
-          children: 'xs',
-        })}
         sm={(baseProps) => ({
           ...baseProps,
           style: { ...baseProps.style, backgroundColor: 'palevioletred' },
@@ -62,19 +51,14 @@ const App = () => {
           style: { ...baseProps.style, backgroundColor: 'brown' },
           children: 'md',
         })}
-        lg={(baseProps) => ({
-          ...baseProps,
-          style: { ...baseProps.style, backgroundColor: 'green' },
-          children: 'lg',
-        })}
-      />
+      >
+        overridden
+      </HostComponentWithHOC>
       <CustomComponentWithHook
         someColor="#000000"
         someText="overridden"
-        xs={{ someColor: 'rebeccapurple', someText: 'xs' }}
         sm={{ someColor: 'palevioletred', someText: 'sm' }}
         md={{ someColor: 'brown', someText: 'md' }}
-        lg={{ someColor: 'green', someText: 'lg' }}
       />
     </ScreenClassProvider>
   );

examples/typescript/responsiveSystem.ts

@@ -10,6 +10,7 @@ const breakpoints = {
 export const { ScreenClassProvider, useResponsiveProps, responsive } = createResponsiveSystem({
   defaultScreenClass: 'lg',
   breakpoints,
+  mode: 'desktop-first',
 });
 
 // ResponsiveProps takes 2 type args: the breakpoints, and the props

jest.config.js

@@ -4,4 +4,5 @@ module.exports = {
   globals: {
     __DEV__: true,
   },
+  setupFilesAfterEnv: ['./test/setup.ts'],
 };

src/index.tsx

@@ -79,6 +79,17 @@ export type ScreenClassConfiguration<B extends ScreenClassBreakpoints> = {
    * }
    */
   breakpoints: B;
+
+  /**
+   * Controls the way that overrides are applied
+   *
+   * "no-cascade" -> only apply overrides on the exact screen class
+   * "mobile-first" -> override on matching screen class and larger
+   * "desktop-first" -> override on matching screen class and smaller
+   *
+   * @default "no-cascade"
+   */
+  cascadeMode?: 'no-cascade' | 'mobile-first' | 'desktop-first';
 };
 
 export type ScreenClass<B extends ScreenClassBreakpoints> = keyof B;
@@ -95,7 +106,7 @@ export type ResponsiveProps<B extends ScreenClassBreakpoints, P extends {}> = Om
 export function createResponsiveSystem<B extends ScreenClassBreakpoints>(
   screenClassConfiguration: ScreenClassConfiguration<B>,
 ) {
-  const { defaultScreenClass, breakpoints } = screenClassConfiguration;
+  const { defaultScreenClass, breakpoints, cascadeMode = 'no-cascade' } = screenClassConfiguration;
 
   //
   // ─── VALIDATE ───────────────────────────────────────────────────────────────────
@@ -135,6 +146,24 @@ export function createResponsiveSystem<B extends ScreenClassBreakpoints>(
 
   const sortedScreenClasses = sortedScreenClassBreakpoints.map(([screenClass]) => screenClass);
 
+  /**
+   * Mobile-First Screen Classes include the current screen class and all smaller
+   *
+   * The should be applied smallest to largest
+   */
+  function getMobileFirstScreenClasses(breakpoint: keyof B) {
+    return sortedScreenClasses.slice(0, sortedScreenClasses.indexOf(breakpoint) + 1);
+  }
+
+  /**
+   * Desktop-First Screen Classes include the current screen class and all larger
+   *
+   * They should be applied from largest to smallest
+   */
+  function getDesktopFirstScreenClasses(breakpoint: keyof B) {
+    return sortedScreenClasses.slice(sortedScreenClasses.indexOf(breakpoint)).reverse();
+  }
+
   //
   // ─── CONTEXT ────────────────────────────────────────────────────────────────────
   //
@@ -242,14 +271,33 @@ export function createResponsiveSystem<B extends ScreenClassBreakpoints>(
 
     // TypeScript: this is correct, but TS is having trouble confirming that it will be type P
     const baseProps = omit(props, sortedScreenClasses) as P;
-    const overrides =
-      props[currentScreenClass] !== undefined ? props[currentScreenClass] : ({} as Partial<P>);
 
-    if (typeof overrides === 'function') {
-      return overrides(baseProps);
+    let applicableScreenClasses = [];
+    switch (cascadeMode) {
+      case 'mobile-first':
+        applicableScreenClasses = getMobileFirstScreenClasses(currentScreenClass);
+        break;
+      case 'desktop-first':
+        applicableScreenClasses = getDesktopFirstScreenClasses(currentScreenClass);
+        break;
+      case 'no-cascade':
+      default:
+        applicableScreenClasses = [currentScreenClass];
     }
 
-    return { ...baseProps, ...overrides };
+    // apply each screen class on top of the baseProps
+    // the screenClasses should be sorted in the order in which they should be applied
+    // e.g. mobile-first should apply smallest -> largest
+    // e.g. desktop-first should apply largest -> smallest
+    // we assume that the sorting is already done
+    return applicableScreenClasses.reduce((o, sc) => {
+      const override = props[sc] ?? {};
+      if (typeof override === 'function') {
+        return override(o);
+      } else {
+        return { ...o, ...override };
+      }
+    }, baseProps);
   }
 
   // In order to support refs, we need to use forwardRef

test/common.tsx

@@ -0,0 +1,81 @@
+import * as React from 'react';
+import { ResponsiveProps, createResponsiveSystem, ScreenClassConfiguration } from '../src';
+import { render } from '@testing-library/react';
+
+const breakpoints = {
+  xs: 500,
+  sm: 750,
+  md: 1000,
+  lg: Infinity,
+};
+
+const expectedMediaQueries: { [K in keyof typeof breakpoints]: string } = {
+  xs: '(max-width: 500px)',
+  sm: '(min-width: 501px) and (max-width: 750px)',
+  md: '(min-width: 751px) and (max-width: 1000px)',
+  lg: '(min-width: 1001px)',
+};
+
+/**
+ * Mocks the window.matchMedia fn such that it will return `matches = true` when asked to match the given screen class's media query
+ *
+ * This mock will assert that every input passed to matchMedia is one of our expected media queries
+ * and will return `matches = true` only if the media query matches the expected media query
+ * for the screenClass provided to `mockMatchMedia`
+ */
+function mockMatchMedia(screenClass: keyof typeof breakpoints) {
+  window.matchMedia = jest.fn().mockImplementation((query) => {
+    // assert that every media query that we try to match is an "expected" media query
+    expect(query).toBeInList(Object.values(expectedMediaQueries));
+
+    return {
+      // match only if we get the media query for the given screen class
+      matches: query === expectedMediaQueries[screenClass],
+      media: query,
+      onchange: null,
+      addListener: jest.fn(), // deprecated
+      removeListener: jest.fn(), // deprecated
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    };
+  });
+}
+
+export function makeScreenClassTester(
+  responsiveSystemConfiguration: Omit<ScreenClassConfiguration<typeof breakpoints>, 'breakpoints'>,
+) {
+  const { ScreenClassProvider, responsive, useResponsiveProps } = createResponsiveSystem({
+    breakpoints,
+    ...responsiveSystemConfiguration,
+  });
+
+  const ResponsiveCompWithHOC = responsive((props: React.PropsWithChildren<{ text: string }>) => (
+    <div data-testid="hoc-comp">{props.text}</div>
+  ));
+
+  const ResponsiveCompWithHook: React.FC<ResponsiveProps<typeof breakpoints, { text: string }>> = (
+    props,
+  ) => {
+    const responsiveProps = useResponsiveProps(props);
+
+    return <div data-testid="hook-comp">{responsiveProps.text}</div>;
+  };
+
+  return function testScreenClass(
+    screenClass: keyof typeof breakpoints,
+    expected: keyof typeof breakpoints | 'base',
+  ) {
+    mockMatchMedia(screenClass);
+
+    const { getByTestId } = render(
+      <ScreenClassProvider>
+        <ResponsiveCompWithHOC text="base" sm={{ text: 'sm' }} md={{ text: 'md' }} />
+        <ResponsiveCompWithHook text="base" sm={{ text: 'sm' }} md={{ text: 'md' }} />
+      </ScreenClassProvider>,
+    );
+
+    expect(getByTestId('hoc-comp').innerHTML).toBe(expected);
+    expect(getByTestId('hook-comp').innerHTML).toBe(expected);
+  };
+}

test/desktopFirst.spec.tsx

@@ -0,0 +1,21 @@
+import { makeScreenClassTester } from './common';
+
+const testScreenClass = makeScreenClassTester({
+  defaultScreenClass: 'lg',
+  cascadeMode: 'desktop-first',
+});
+
+describe('desktop-first', () => {
+  it('no xs inherits sm', () => {
+    testScreenClass('xs', 'sm');
+  });
+  it('sm inherits sm', () => {
+    testScreenClass('sm', 'sm');
+  });
+  it('md inherits md', () => {
+    testScreenClass('md', 'md');
+  });
+  it('no lg inherits base', () => {
+    testScreenClass('lg', 'base');
+  });
+});