Merge pull request #2367 from alphagov/add-negative-spacing

Allow `govuk-spacing` to output negative spacing

Author: Vanita Barrett

CHANGELOG.md

@@ -10,6 +10,14 @@ You can now use the `govuk-!-text-align-left`, `govuk-!-text-align-centre` and `
 
 This was added in [pull request #2368: Add text align override classes](https://github.com/alphagov/govuk-frontend/pull/2368).
 
+#### Define negative spacing using the `govuk-spacing` function
+
+You can now pass the negative equivalent of a point from the spacing scale to the `govuk-spacing` function to get negative spacing.
+
+For example, `govuk-spacing(1)` returns `5px`, and `govuk-spacing(-1)` returns `-5px`.
+
+This was added in [pull request #2367: Allow govuk-spacing to output negative spacing](https://github.com/alphagov/govuk-frontend/pull/2367).
+
 ### Fixes
 
 - [#2366: Fix panel text overflowing when zoomed in on mobile #2366](https://github.com/alphagov/govuk-frontend/pull/2366)

src/govuk/helpers/_spacing.scss

@@ -8,15 +8,26 @@
 ///
 /// Returns measurement corresponding to the spacing point requested.
 ///
-/// @param {Number} $spacing-point - Point on the spacing scale (set in `settings/_spacing.sccs`)
+/// @param {Number} $spacing-point - Point on the spacing scale
+///  (set in `settings/_spacing.scss`)
 ///
-/// @returns {String} Spacing Measurement eg. 10px
+/// @returns {String} Spacing measurement eg. 10px
 ///
 /// @example scss
 ///   .element {
 ///     padding: govuk-spacing(5);
-///     top: govuk-spacing(2) !important; // if `!important` is required
 ///   }
+///
+/// @example scss Using negative spacing
+///   .element {
+///     margin-top: govuk-spacing(-1);
+///   }
+///
+/// @example scss Marking spacing declarations as important
+///   .element {
+///     margin-top: govuk-spacing(1) !important;
+///   }
+///
 /// @access public
 
 @function govuk-spacing($spacing-point) {
@@ -27,11 +38,18 @@
     + "#{$actual-input-type}.";
   }
 
+  $is-negative: false;
+  @if ($spacing-point < 0) {
+    $is-negative: true;
+    $spacing-point: abs($spacing-point);
+  }
+
   @if not map-has-key($govuk-spacing-points, $spacing-point) {
     @error "Unknown spacing variable `#{$spacing-point}`. Make sure you are using a point from the spacing scale in `_settings/spacing.scss`.";
   }
 
-  @return map-get($govuk-spacing-points, $spacing-point);
+  $value: map-get($govuk-spacing-points, $spacing-point);
+  @return if($is-negative, $value * -1, $value);
 }
 
 /// Responsive spacing

src/govuk/helpers/spacing.test.js

@@ -21,6 +21,7 @@ const sassBootstrap = `
 
   // Emulates data from _settings/spacing.scss
   $govuk-spacing-points: (
+    0: 0,
     2: 15px
   );
 
@@ -52,7 +53,22 @@ describe('@function govuk-spacing', () => {
         top: 15px; }`)
   })
 
-  it('throws an exception when passed anything other than a number', async () => {
+  it('returns CSS for a property based on a negative spacing point', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        top: govuk-spacing(-2)
+      }`
+
+    const results = await renderSass({ data: sass, ...sassConfig })
+
+    expect(results.css.toString().trim()).toBe(outdent`
+      .foo {
+        top: -15px; }`)
+  })
+
+  it('throws an error when passed anything other than a number', async () => {
     const sass = `
       ${sassBootstrap}
 
@@ -66,6 +82,51 @@ describe('@function govuk-spacing', () => {
         'Expected a number (integer), but got a string.'
       )
   })
+
+  it('throws an error when passed a non-existent point', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        top: govuk-spacing(999)
+      }`
+
+    await expect(renderSass({ data: sass, ...sassConfig }))
+      .rejects
+      .toThrow(
+        'Unknown spacing variable `999`. Make sure you are using a point from the spacing scale in `_settings/spacing.scss`.'
+      )
+  })
+
+  it('throws an error when passed a non-existent negative point', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        top: govuk-spacing(-999)
+      }`
+
+    await expect(renderSass({ data: sass, ...sassConfig }))
+      .rejects
+      .toThrow(
+        'Unknown spacing variable `999`. Make sure you are using a point from the spacing scale in `_settings/spacing.scss`.'
+      )
+  })
+
+  it('handles negative zero', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        top: govuk-spacing(-0)
+      }`
+
+    const results = await renderSass({ data: sass, ...sassConfig })
+
+    expect(results.css.toString().trim()).toBe(outdent`
+      .foo {
+        top: 0; }`)
+  })
 })
 
 describe('@mixin _govuk-responsive-spacing', () => {