diff --git a/CHANGELOG.md b/CHANGELOG.md index b745b37b72..25345c6c9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,9 @@ New features: - We're now using ES6 Modules and [rollup](https://rollupjs.org/guide/en) to distribute our JavaScript. (PR [#652](https://github.com/alphagov/govuk-frontend/pull/652)) +- Vendor-in SassMQ functionality, write tests and remove external dependency + (PR [#657](https://github.com/alphagov/govuk-frontend/pull/657)) + Internal: - Update publishing docs (PR [#651](https://github.com/alphagov/govuk-frontend/pull/651)) diff --git a/config/.sass-lint.yml b/config/.sass-lint.yml index 94d4c34bd3..68c6f7fecf 100644 --- a/config/.sass-lint.yml +++ b/config/.sass-lint.yml @@ -233,6 +233,10 @@ rules: # https://github.com/sasstools/sass-lint/blob/master/docs/rules/no-vendor-prefixes.md no-vendor-prefixes: 0 + # Rule no-warn will enforce that @warn statements are not allowed to be used. + # https://github.com/sasstools/sass-lint/blob/master/docs/rules/no-warn.md + no-warn: 0 + # Rule placeholder-in-extend will enforce whether extends should only include placeholder selectors. # https://github.com/sasstools/sass-lint/blob/master/docs/rules/placeholder-in-extend.md placeholder-in-extend: 2 diff --git a/package-lock.json b/package-lock.json index c95c67efb4..87fd9e46d9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14094,11 +14094,6 @@ } } }, - "sass-mq": { - "version": "3.3.2", - "resolved": "https://registry.npmjs.org/sass-mq/-/sass-mq-3.3.2.tgz", - "integrity": "sha1-NHLgTDGkMrzVWztgTtxyrppN7xo=" - }, "sax": { "version": "1.2.4", "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz", diff --git a/package.json b/package.json index 6cf5c785ca..6c04f269b9 100644 --- a/package.json +++ b/package.json @@ -70,8 +70,7 @@ "dependencies": { "gulp-if": "^2.0.2", "outdent": "^0.5.0", - "postcss-scss": "^1.0.0", - "sass-mq": "^3.3.2" + "postcss-scss": "^1.0.0" }, "optionalDependencies": { "fsevents": "*" diff --git a/packages/globals/package.json b/packages/globals/package.json index 8b6b5db85e..6863394968 100644 --- a/packages/globals/package.json +++ b/packages/globals/package.json @@ -1,7 +1,4 @@ { "name": "@govuk-frontend/globals", - "version": "0.0.28-alpha", - "dependencies": { - "sass-mq": "^3.3.2" - } + "version": "0.0.28-alpha" } diff --git a/src/globals/helpers/_media-queries.scss b/src/globals/helpers/_media-queries.scss index d30f1c3a93..1fb3fc1f1f 100644 --- a/src/globals/helpers/_media-queries.scss +++ b/src/globals/helpers/_media-queries.scss @@ -1,16 +1,318 @@ -// We use sass-mq module for media queries +@charset "UTF-8"; +// Fixes an issue where Ruby locale is not set properly +// See https://github.com/sass-mq/sass-mq/pull/10 -// This is a horrible, horrible hack to prevent the 'dev mode' CSS to display -// the current breakpoint from being included multiple times. -// -// We can't use the `exports` mixin for this because import directives cannot be -// used within control directives 😠 -$sass-mq-already-included: false !default; +// This is a vendored version of SassMQ utility for composing media quesries +// File is taken from https://github.com/sass-mq/sass-mq +// Based on version 4.0.2 -@if $sass-mq-already-included { - $mq-show-breakpoints: (); +@import "../tools/exports"; +@import "../settings/colours-palette"; +@import "../settings/spacing"; + +// map colours to local variables +$mq-indicator-background: $govuk-yellow-50; +$mq-indicator-text: $govuk-black; +$mq-indicator-border: $govuk-yellow; + +/// Base font size on the `` element +/// @type Number (unit) +$mq-base-font-size: 16px !default; +/// Responsive mode +/// +/// Set to `false` to enable support for browsers that do not support @media queries, +/// (IE <= 8, Firefox <= 3, Opera <= 9) +/// +/// You could create a stylesheet served exclusively to older browsers, +/// where @media queries are rasterized +/// +/// @example scss +/// // old-ie.scss +/// $mq-responsive: false; +/// @import 'main'; // @media queries in this file will be rasterized up to $mq-static-breakpoint +/// // larger breakpoints will be ignored +/// +/// @type Boolean +/// @link https://github.com/sass-mq/sass-mq#responsive-mode-off Disabled responsive mode documentation +$mq-responsive: true !default; +/// Breakpoint list +/// +/// Name your breakpoints in a way that creates a ubiquitous language +/// across team members. It will improve communication between +/// stakeholders, designers, developers, and testers. +/// +/// @type Map +/// @link https://github.com/sass-mq/sass-mq#seeing-the-currently-active-breakpoint Full documentation and examples +$mq-breakpoints: (mobile: 320px, tablet: 740px, desktop: 980px, wide: 1300px) !default; +/// Static breakpoint (for fixed-width layouts) +/// +/// Define the breakpoint from $mq-breakpoints that should +/// be used as the target width for the fixed-width layout +/// (i.e. when $mq-responsive is set to 'false') in a old-ie.scss +/// +/// @example scss +/// // tablet-only.scss +/// // +/// // Ignore all styles above tablet breakpoint, +/// // and fix the styles (e.g. layout) at tablet width +/// $mq-responsive: false; +/// $mq-static-breakpoint: tablet; +/// @import 'main'; // @media queries in this file will be rasterized up to tablet +/// // larger breakpoints will be ignored +/// +/// @type String +/// @link https://github.com/sass-mq/sass-mq#adding-custom-breakpoints Full documentation and examples +$mq-static-breakpoint: desktop !default; +/// Show breakpoints in the top right corner +/// +/// If you want to display the currently active breakpoint in the top +/// right corner of your site during development, add the breakpoints +/// to this list, ordered by width, e.g. (mobile, tablet, desktop). +/// +/// @type map +$mq-show-breakpoints: () !default; +/// Customize the media type (e.g. `@media screen` or `@media print`) +/// By default sass-mq uses an "all" media type (`@media all and …`) +/// +/// @type String +/// @link https://github.com/sass-mq/sass-mq#changing-media-type Full documentation and examples +$mq-media-type: all !default; +/// Convert pixels to ems +/// +/// @param {Number} $px - value to convert +/// @param {Number} $base-font-size ($mq-base-font-size) - `` font size +/// +/// @example scss +/// $font-size-in-ems: mq-px2em(16px); +/// p { font-size: mq-px2em(16px); } +/// +/// @requires $mq-base-font-size +/// @returns {Number} +@function mq-px2em($px, $base-font-size: $mq-base-font-size) { + @if unitless($px) { + @warn "Assuming #{$px} to be in pixels, attempting to convert it into pixels."; + @return mq-px2em($px * 1px, $base-font-size); + } + @else if unit($px) == em { + @return $px; + } + @return ($px / $base-font-size) * 1em; +} + +/// Get a breakpoint's width +/// +/// @param {String} $name - Name of the breakpoint. One of $mq-breakpoints +/// +/// @example scss +/// $tablet-width: mq-get-breakpoint-width(tablet); +/// @media (min-width: mq-get-breakpoint-width(desktop)) {} +/// +/// @requires {Variable} $mq-breakpoints +/// +/// @returns {Number} Value in pixels +@function mq-get-breakpoint-width($name, $breakpoints: $mq-breakpoints) { + @if map-has-key($breakpoints, $name) { + @return map-get($breakpoints, $name); + }@else { + @error "Breakpoint #{$name} wasn't found in $breakpoints."; + } +} + +/// Media Query mixin +/// +/// @param {String | Boolean} $from (false) - One of $mq-breakpoints +/// @param {String | Boolean} $until (false) - One of $mq-breakpoints +/// @param {String | Boolean} $and (false) - Additional media query parameters +/// @param {String} $media-type ($mq-media-type) - Media type: screen, print… +/// +/// @ignore Undocumented API, for advanced use only: +/// @ignore @param {Map} $breakpoints ($mq-breakpoints) +/// @ignore @param {String} $static-breakpoint ($mq-static-breakpoint) +/// +/// @content styling rules, wrapped into a @media query when $responsive is true +/// +/// @requires {Variable} $mq-media-type +/// @requires {Variable} $mq-breakpoints +/// @requires {Variable} $mq-static-breakpoint +/// @requires {function} mq-px2em +/// @requires {function} mq-get-breakpoint-width +/// +/// @link https://github.com/sass-mq/sass-mq#responsive-mode-on-default Full documentation and examples +/// +/// @example scss +/// .element { +/// @include mq($from: mobile) { +/// color: red; +/// } +/// @include mq($until: tablet) { +/// color: blue; +/// } +/// @include mq(mobile, tablet) { +/// color: green; +/// } +/// @include mq($from: tablet, $and: '(orientation: landscape)') { +/// color: teal; +/// } +/// @include mq(950px) { +/// color: hotpink; +/// } +/// @include mq(tablet, $media-type: screen) { +/// color: hotpink; +/// } +/// // Advanced use: +/// $my-breakpoints: (L: 900px, XL: 1200px); +/// @include mq(L, $breakpoints: $my-breakpoints, $static-breakpoint: L) { +/// color: hotpink; +/// } +/// } +@mixin mq($from: false, $until: false, $and: false, $media-type: $mq-media-type, $breakpoints: $mq-breakpoints, $responsive: $mq-responsive, $static-breakpoint: $mq-static-breakpoint) { + $min-width: 0; + $max-width: 0; + $media-query: ""; // From: this breakpoint (inclusive) + @if $from { + @if type-of($from) == number { + $min-width: mq-px2em($from); + } @else { + $min-width: mq-px2em(mq-get-breakpoint-width($from, $breakpoints)); + } + } // Until: that breakpoint (exclusive) + @if $until { + @if type-of($until) == number { + $max-width: mq-px2em($until); + } @else { + $max-width: mq-px2em(mq-get-breakpoint-width($until, $breakpoints)) - .01em; + } + } // Responsive support is disabled, rasterize the output outside @media blocks + // The browser will rely on the cascade itself. + @if $responsive == false { + $static-breakpoint-width: mq-get-breakpoint-width($static-breakpoint, $breakpoints); + $target-width: mq-px2em($static-breakpoint-width); // Output only rules that start at or span our target width + @if ( $and == false and $min-width <= $target-width and ( $until == false or $max-width >= $target-width)) { + @content; + } + } @else { // Responsive support is enabled, output rules inside @media queries + @if $min-width != 0 { + $media-query: "#{$media-query} and (min-width: #{$min-width})"; + } + @if $max-width != 0 { + $media-query: "#{$media-query} and (max-width: #{$max-width})"; + } + @if $and { + $media-query: "#{$media-query} and #{$and}"; + } // Remove unnecessary media query prefix 'all and ' + @if ($media-type == "all" and $media-query != "") { + $media-type: ""; + $media-query: str-slice(unquote($media-query), 6); + } + @media #{$media-type + $media-query} { + @content; + } + } +} + +/// Quick sort +/// +/// @author Sam Richards +/// @access private +/// @param {List} $list - List to sort +/// @returns {List} Sorted List +@function _mq-quick-sort($list) { + $less: (); + $equal: (); + $large: (); + @if length($list) > 1 { + $seed: nth($list, ceil(length($list) / 2)); + @each $item in $list { + @if ($item == $seed) { + $equal: append($equal, $item); + }@else if ($item < $seed) { + $less: append($less, $item); + }@else if ($item > $seed) { + $large: append($large, $item); + } + } + @return join(join(_mq-quick-sort($less), $equal), _mq-quick-sort($large)); + } + @return $list; } -@import "./node_modules/sass-mq/mq"; +/// Sort a map by values (works with numbers only) +/// +/// @access private +/// @param {Map} $map - Map to sort +/// @returns {Map} Map sorted by value +@function _mq-map-sort-by-value($map) { + $map-sorted: (); + $map-keys: map-keys($map); + $map-values: map-values($map); + $map-values-sorted: _mq-quick-sort($map-values); // Reorder key/value pairs based on key values + @each $value in $map-values-sorted { + $index: index($map-values, $value); + $key: nth($map-keys, $index); + $map-sorted: map-merge($map-sorted, ($key: $value)); // Unset the value in $map-values to prevent the loop + // from finding the same index twice + $map-values: set-nth($map-values, $index, 0); + } + @return $map-sorted; +} + +/// Add a breakpoint +/// +/// @param {String} $name - Name of the breakpoint +/// @param {Number} $width - Width of the breakpoint +/// +/// @requires {Variable} $mq-breakpoints +/// +/// @example scss +/// @include mq-add-breakpoint(tvscreen, 1920px); +/// @include mq(tvscreen) {} +@mixin mq-add-breakpoint($name, $width) { + $new-breakpoint: ($name: $width); + $mq-breakpoints: map-merge($mq-breakpoints, $new-breakpoint) !global; + $mq-breakpoints: _mq-map-sort-by-value($mq-breakpoints) !global; +} + +/// Show the active breakpoint in the top right corner of the viewport +/// @link https://github.com/sass-mq/sass-mq#seeing-the-currently-active-breakpoint +/// +/// @param {List} $show-breakpoints ($mq-show-breakpoints) - List of breakpoints to show in the top right corner +/// @param {Map} $breakpoints ($mq-breakpoints) - Breakpoint names and sizes +/// +/// @requires {Variable} $mq-breakpoints +/// @requires {Variable} $mq-show-breakpoints +/// +/// @example scss +/// // Show breakpoints using global settings +/// @include mq-show-breakpoints; +/// +/// // Show breakpoints using custom settings +/// @include mq-show-breakpoints((L, XL), (S: 300px, L: 800px, XL: 1200px)); +@mixin mq-show-breakpoints($show-breakpoints: $mq-show-breakpoints, $breakpoints: $mq-breakpoints) { + body:before { + position: fixed; + z-index: 100; // Loop through the breakpoints that should be shown + top: 0; + right: 0; + padding: $govuk-spacing-scale-1; + border-bottom: 1px solid $mq-indicator-border; + border-left: 1px solid $mq-indicator-border; + color: $mq-indicator-text; + background-color: $mq-indicator-background; + font: small-caption; + pointer-events: none; -$sass-mq-already-included: true; + @each $show-breakpoint in $show-breakpoints { + $width: mq-get-breakpoint-width($show-breakpoint, $breakpoints); + @include mq($show-breakpoint, $breakpoints: $breakpoints) { + content: "#{$show-breakpoint} ≥ #{$width} (#{mq-px2em($width)})"; + } + } + } +} + +@include govuk-exports("govuk-sass-mq") { + + @if length($mq-show-breakpoints) > 0 { + @include mq-show-breakpoints; + } +} diff --git a/src/globals/helpers/media-queries.test.js b/src/globals/helpers/media-queries.test.js new file mode 100644 index 0000000000..919fc6deae --- /dev/null +++ b/src/globals/helpers/media-queries.test.js @@ -0,0 +1,270 @@ +/* eslint-env jest */ + +const util = require('util') + +const configPaths = require('../../../config/paths.json') + +const sass = require('node-sass') +const sassRender = util.promisify(sass.render) +const outdent = require('outdent') + +const sassConfig = { + includePaths: [ configPaths.src ], + outputStyle: 'compressed' +} +describe('sass-mq', () => { + describe('mq-px2em function', () => { + it('converts px value to em', async () => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + width: mq-px2em(320px); + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('.foo{width:20em}') + }) + + it('assumes unitless value is px and converts it to em', async () => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + width: mq-px2em(640); + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('.foo{width:40em}') + }) + + it('accepts em value and outputs the same em value', async () => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + width: mq-px2em(40em); + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('.foo{width:40em}') + }) + + it('$mq-base-font-size change results in updated calculation', async () => { + const sass = ` + $mq-base-font-size: 19px; + @import "globals/helpers/media-queries"; + + .foo { + width: mq-px2em(320px); + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('.foo{width:16.84211em}') + }) + }) + + describe('@mq-get-breakpoint-width function', () => { + it('outputs media query value from the breakpoint map', async () => { + const sass = ` + $my-breakpoints: ( + mobile: 320px, + tablet: 641px, + desktop: 769px + ); + @import "globals/helpers/media-queries"; + + .foo { + @media (min-width: mq-get-breakpoint-width('desktop', $my-breakpoints)) { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (min-width: 769px){.foo{color:red}}') + }) + + it('errors if the specified breakpoint does not exists in the map', async () => { + const sass = ` + $my-breakpoints: ( + mobile: 320px, + tablet: 641px, + desktop: 769px + ); + + @import "globals/helpers/media-queries"; + + $value: mq-get-breakpoint-width('massive', $my-breakpoints); + ` + await expect(sassRender({ data: sass, ...sassConfig })) + .rejects + .toThrow("Breakpoint massive wasn't found in $breakpoints.") + }) + }) + + describe('@mq-add-breakpoint mixin', () => { + it('outputs a custom defined breakpoint', async () => { + const sass = ` + @import "globals/helpers/media-queries"; + + @include mq-add-breakpoint(tvscreen, 1920px); + + .hide-on-tv { + @include mq(tvscreen) { + display: none; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (min-width: 120em){.hide-on-tv{display:none}}') + }) + }) + + describe('@mq-show-breakpoints mixin', () => { + it('outputs all the specified breakpoints', async () => { + const sass = ` + @import "globals/helpers/media-queries"; + @include mq-show-breakpoints((L, XL), (L: 800px, XL: 1200px)); + ` + const sassConfig = { + includePaths: [ configPaths.src ], + outputStyle: 'nested' + } + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString() + .trim()) + .toBe(outdent` + @charset \"UTF-8\"; + body:before { + position: fixed; + z-index: 100; + top: 0; + right: 0; + padding: 5px; + border-bottom: 1px solid #ffbf47; + border-left: 1px solid #ffbf47; + color: #0b0c0c; + background-color: #ffdf94; + font: small-caption; + pointer-events: none; } + @media (min-width: 50em) { + body:before { + content: \"L ≥ 800px (50em)\"; } } + @media (min-width: 75em) { + body:before { + content: \"XL ≥ 1200px (75em)\"; } }`) + }) + }) + + describe('@mq mixin', () => { + it('outputs "min-width" media query', async() => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + @include mq($from: 20em) { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (min-width: 20em){.foo{color:red}}') + }) + + it('outputs "max-width" media query', async() => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + @include mq($until: 20em) { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (max-width: 20em){.foo{color:red}}') + }) + + it('outputs "min-width" and max-width" media queries', async() => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + @include mq(20em,40em) { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (min-width: 20em) and (max-width: 40em){.foo{color:red}}') + }) + + it('outputs additional custom directives', async() => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + @include mq($until:40em, $and:'(orientation: landscape)') { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media (max-width: 40em) and (orientation: landscape){.foo{color:red}}') + }) + + it('outputs the correct media type', async() => { + const sass = ` + @import "globals/helpers/media-queries"; + + .foo { + @include mq($until:40em, $media-type: 'aural') { + color: red; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('@media aural and (max-width: 40em){.foo{color:red}}') + }) + + it('only outputs static breapoint styles', async() => { + const sass = ` + $mq-breakpoints: ( + mobile: 320px, + tablet: 740px, + desktop: 980px, + wide: 1300px + ); + + $mq-responsive: false; + $mq-static-breakpoint: desktop; + + @import "globals/helpers/media-queries"; + + .foo { + @include mq($until: tablet) { + color: lawngreen; + } + @include mq($from: desktop) { + color: forestgreen; + } + }` + + const results = await sassRender({ data: sass, ...sassConfig }) + + expect(results.css.toString().trim()).toBe('.foo{color:forestgreen}') + }) + }) +})