Allow govuk-spacing to output negative spacing

Occasionally, users need to use the `govuk-spacing` class to output negative spacing, for example to add a negative margin to bring elements closer together.

There are currently a few ways to do this.

You can use `- govuk-spacing(n)` but the extra space is required, and it looks like a calculation (and may be interpreted as such in some contexts).

You can also multiply the result of the function call by -1, for example `govuk-spacing(n) * -1`, but this feels a little clunky.

To make it easier for users to do this, allow govuk-spacing to accept a negative version of a point on the spacing scale, and output the equivalent spacing from the scale multiplied by -1.

fixup! Allow govuk-spacing to output negative spacing

Author: 36degrees

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,6 +53,21 @@ describe('@function govuk-spacing', () => {
         top: 15px; }`)
   })
 
+  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}
@@ -81,6 +97,36 @@ describe('@function govuk-spacing', () => {
         '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', () => {