Merge pull request #11436 from ncoden/feat/js-media-query-down-breakpoint-11122

feat: add support for "down" media queries in "MediaQuery.is()" #11122

Author: joeworkman

docs/pages/grid.md

@@ -360,7 +360,7 @@ In order to work around browsers' different rounding behaviors, Foundation will
 
 #### Responsive Gutters
 
-The grid *gutter*—the space between two columns in a row, and the space between the edge of a grid and the edge of the page—is responsive, and becomes wider on larger screens.
+The grid *gutter*—the space between two columns in a row, and the space between the edge of a grid and the edge of the page—is responsive, and becomes larger on larger screens.
 
 Breakpoint | Gutter Size
 -----------|------------

docs/pages/media-queries.md

@@ -18,8 +18,8 @@ tags:
 Foundation for Sites has three core breakpoints:
 
 - **Small:** any screen.
-- **Medium:** any screen 640 pixels or wider.
-- **Large:** any screen 1024 pixels or wider.
+- **Medium:** any screen 640 pixels or larger.
+- **Large:** any screen 1024 pixels or larger.
 
 Many components can be modified at different screen sizes using special *breakpoint classes*. The grid is the most obvious example. In the code below, the left-hand column is six columns wide on small screens, hence `.small-6`. On medium-sized screens, the class `.medium-4` overrides the small style, changing the column to be four wide.
 
@@ -197,22 +197,24 @@ Get the name of the current breakpoint with `MediaQuery.current`.
 Foundation.MediaQuery.current // => 'small', 'medium', etc.
 ```
 
-To see if the screen is currently a certain breakpoint or larger, use `MediaQuery.atLeast`.
-
+You can use `MediaQuery.is()` to check the breakpoint the screen is at.
 ```js
-if (Foundation.MediaQuery.atLeast('medium')) {
-  // True if medium or large
-  // False if small
-}
+Foundation.MediaQuery.is('medium') // => True for "medium" or larger
 ```
 
-To see if the screen is currently a certain breakpoint, use `MediaQuery.is`.
-
+You can also use the `up` (default), `only` and `down` modifiers like in Sass, or use the equivalent `MediaQuery.atLeast()`, `MediaQuery.only()` and `MediaQuery.upTo()`.
 ```js
-if (Foundation.MediaQuery.is('small only')) {
-  // True if small
-  // False if medium or large
-}
+// ↑ True for "medium" or larger (by default)
+Foundation.MediaQuery.is('medium up');
+Foundation.MediaQuery.atLeast('medium');
+
+// → True for "medium" only
+Foundation.MediaQuery.is('medium only');
+Foundation.MediaQuery.only('medium');
+
+// ↓ True for "medium" or larger
+Foundation.MediaQuery.is('medium down');
+Foundation.MediaQuery.upTo('medium');
 ```
 
 To get the media query of a breakpoint, use `MediaQuery.get`.

docs/pages/prototyping-utilities.md

@@ -304,7 +304,7 @@ This creates a tiny separator below the heading of an element and is usually use
 
 ## Font Styling
 
-You can use font styling to style your text. You can change the font styling by adding `font-normal`, `font-bold`, `font-italic` to an element. You can also wider the text of an element with `font-wide`.
+You can use font styling to style your text. You can change the font styling by adding `font-normal`, `font-bold`, `font-italic` to an element. You can also larger the text of an element with `font-wide`.
 
 ```html_example
 <p class="font-wide">Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>

docs/pages/typography-base.md

@@ -61,7 +61,7 @@ Foundation includes styles for all headings—they're balanced and sized alo
 
 ### Header Styles
 
-The framework includes two typographic scales&mdash;one uses a narrow range of sizes for small-sized screens, and the other uses a wider range of sizes for medium- and larger-sized screens. You can change these scales, or add new ones for other breakpoints, by editing the `$header-styles` map in your project's <a href="sass.html#the-settings-file">Settings File</a>.
+The framework includes two typographic scales&mdash;one uses a narrow range of sizes for small-sized screens, and the other uses a larger range of sizes for medium- and larger-sized screens. You can change these scales, or add new ones for other breakpoints, by editing the `$header-styles` map in your project's <a href="sass.html#the-settings-file">Settings File</a>.
 
 <a class="" data-open-video="1:28"><img src="{{root}}assets/img/icons/watch-video-icon.svg" class="video-icon" height="30" width="30" alt=""> Watch this part in video</a>
 

js/foundation.util.mediaQuery.js

@@ -142,20 +142,64 @@ var MediaQuery = {
     return false;
   },
 
+  /**
+   * Checks if the screen is within the given breakpoint.
+   * If smaller than the breakpoint of larger than its upper limit it returns false.
+   * @function
+   * @param {String} size - Name of the breakpoint to check.
+   * @returns {Boolean} `true` if the breakpoint matches, `false` otherwise.
+   */
+  only(size) {
+    return size === this._getCurrentSize();
+  },
+
+  /**
+   * Checks if the screen is within a breakpoint or smaller.
+   * @function
+   * @param {String} size - Name of the breakpoint to check.
+   * @returns {Boolean} `true` if the breakpoint matches, `false` if it's larger.
+   */
+  upTo(size) {
+    const nextSize = this.next(size);
+
+    // If the next breakpoint does not match, the screen is smaller than
+    // the upper limit of this breakpoint.
+    if (nextSize) {
+      return !this.atLeast(nextSize);
+    }
+
+    // If there is no next breakpoint, the "size" breakpoint does not have
+    // an upper limit and the screen will always be within it or smaller.
+    return true;
+  },
+
   /**
    * Checks if the screen matches to a breakpoint.
    * @function
    * @param {String} size - Name of the breakpoint to check, either 'small only' or 'small'. Omitting 'only' falls back to using atLeast() method.
    * @returns {Boolean} `true` if the breakpoint matches, `false` if it does not.
    */
   is(size) {
-    size = size.trim().split(' ');
-    if(size.length > 1 && size[1] === 'only') {
-      if(size[0] === this._getCurrentSize()) return true;
-    } else {
-      return this.atLeast(size[0]);
+    const parts = size.trim().split(' ').filter(p => !!p.length);
+    const [bpSize, bpModifier = ''] = parts;
+
+    // Only the breakpont
+    if (bpModifier === 'only') {
+      return this.only(bpSize);
     }
-    return false;
+    // Up to the breakpoint (included)
+    if (bpModifier === 'down') {
+      return this.atLeast(bpSize);
+    }
+    // At leat the breakpoint (included)
+    if (!bpModifier || bpModifier === 'up') {
+      return this.upTo(bpSize);
+    }
+
+    throw new Error(`
+      Invalid breakpoint passed to MediaQuery.is().
+      Expected a breakpoint name formatted like "<size> <modifier>", got "${size}".
+    `);
   },
 
   /**
@@ -175,6 +219,43 @@ var MediaQuery = {
     return null;
   },
 
+  /**
+   * Get the breakpoint following the given breakpoint.
+   * @function
+   * @param {String} size - Name of the breakpoint.
+   * @returns {String|null} - The name of the following breakpoint, or `null` if the passed breakpoint was the last one.
+   */
+  next(size) {
+    const queryIndex = this.queries.findIndex((q) => this._getQueryName(q) === size);
+    if (queryIndex === -1) {
+      throw new Error(`
+        Unknown breakpoint "${size}" passed to MediaQuery.next().
+        Ensure it is present in your Sass "$breakpoints" setting.
+      `);
+    }
+
+    const nextQuery = this.queries[queryIndex + 1];
+    return nextQuery ? nextQuery.name : null;
+  },
+
+  /**
+   * Returns the name of the breakpoint related to the given value.
+   * @function
+   * @private
+   * @param {String|Object} value - Breakpoint name or query object.
+   * @returns {String} Name of the breakpoint.
+   */
+  _getQueryName(value) {
+    if (typeof value === 'string')
+      return value;
+    if (typeof value === 'object')
+      return value.name;
+    throw new TypeError(`
+      Invalid value passed to MediaQuery._getQueryName().
+      Expected a breakpoint name (String) or a breakpoint query (Object), got "${value}" (${typeof value})
+    `);
+  },
+
   /**
    * Gets the current breakpoint name by testing every breakpoint and returning the last one to match (the biggest one).
    * @function
@@ -192,11 +273,7 @@ var MediaQuery = {
       }
     }
 
-    if (typeof matched === 'object') {
-      return matched.name;
-    } else {
-      return matched;
-    }
+    return matched && this._getQueryName(matched);
   },
 
   /**