[SPIKE] Update to simplified grid layout from GOV.UK Frontend

.npmignore

@@ -0,0 +1 @@
+*.test.*

jest.config.js

@@ -16,12 +16,21 @@ module.exports = {
 
   projects: [
     {
-      displayName: 'JSDom',
+      displayName: 'JavaScript unit tests',
+      testMatch: [
+        '**/*.unit.test.{js,mjs}',
+
+        // Exclude integration tests
+        '!<rootDir>/tests/integration/**'
+      ]
+    },
+    {
+      displayName: 'JavaScript behaviour tests',
       testEnvironment: 'jsdom',
       testMatch: ['<rootDir>/tests/integration/jsdom/**/*.test.js']
     },
     {
-      displayName: 'Pupppeteer',
+      displayName: 'JavaScript component tests',
       globalSetup: 'jest-environment-puppeteer/setup',
       globalTeardown: 'jest-environment-puppeteer/teardown',
       testEnvironment: 'jest-environment-puppeteer',

package.json

@@ -58,6 +58,7 @@
     "jest-environment-jsdom": "^29.7.0",
     "jest-puppeteer": "^11.0.0",
     "nunjucks": "^3.2.4",
+    "outdent": "^0.8.0",
     "plugin-error": "^2.0.1",
     "postcss": "^8.5.2",
     "postcss-markdown": "^1.3.0",

packages/core/objects/_grid.scss

@@ -5,11 +5,24 @@
 ////
 
 @include govuk-exports("govuk/objects/grid") {
-  @include govuk-grid-row;
-  @include govuk-grid-column(one-quarter);
-  @include govuk-grid-column(one-third);
-  @include govuk-grid-column(one-half);
-  @include govuk-grid-column(two-thirds);
-  @include govuk-grid-column(three-quarters);
-  @include govuk-grid-column(full);
+  .nhsuk-grid-row {
+    @include clearfix;
+    margin-right: -($nhsuk-gutter-half);
+    margin-left: -($nhsuk-gutter-half);
+  }
+
+  // These *must* be defined in a separate loop as they have the same
+  // specificity as the non-breakpoint specific classes, so need to appear before
+  // them in the outputted CSS
+  @each $width in map-keys($nhsuk-grid-widths) {
+    .nhsuk-grid-column-#{$width}-from-tablet {
+      @include govuk-grid-column($width, $at: tablet, $class: false);
+    }
+  }
+
+  @each $width in map-keys($nhsuk-grid-widths) {
+    .nhsuk-grid-column-#{$width} {
+      @include govuk-grid-column($width, $class: false);
+    }
+  }
 }

packages/core/settings/_globals.scss

@@ -1,3 +1,5 @@
+@use "sass:math";
+
 ////
 /// Globals
 ///
@@ -32,6 +34,17 @@ $nhsuk-page-width: 960px !default;
 $nhsuk-gutter: 32px;
 $nhsuk-gutter-half: $nhsuk-gutter * 0.5;
 
+/// Map of grid column widths
+
+$nhsuk-grid-widths: (
+  one-quarter: math.percentage(math.div(1, 4)),
+  one-third: math.percentage(math.div(1, 3)),
+  one-half: math.percentage(math.div(1, 2)),
+  two-thirds: math.percentage(math.div(2, 3)),
+  three-quarters: math.percentage(math.div(3, 4)),
+  full: 100%
+) !default;
+
 /// Border sizes
 
 $nhsuk-border-width-inset-text: 8px !default;

packages/core/tools/_grid.scss

@@ -1,96 +1,111 @@
+@use "sass:map";
+
 ////
 /// Grid
 ///
 /// @group tools
 /// @link https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
 ////
 
-@use "sass:map";
-@use "sass:math";
-
-/// Map of grid column widths
-
-$_nhsuk-grid-widths: (
-  one-quarter: math.percentage(math.div(1, 4)),
-  one-third: math.percentage(math.div(1, 3)),
-  one-half: math.percentage(math.div(1, 2)),
-  two-thirds: math.percentage(math.div(2, 3)),
-  three-quarters: math.percentage(math.div(3, 4)),
-  full: 100%
-) !default;
-
 /// Grid width percentage
 ///
 /// @param {String} $key - Name of grid width (e.g. two-thirds)
 /// @return {Number} Percentage width
 /// @throw if `$key` is not a valid grid width
 
-@function grid-width($key) {
-  @if map.has-key($_nhsuk-grid-widths, $key) {
-    @return map.get($_nhsuk-grid-widths, $key);
+@function govuk-grid-width($key) {
+  @if map.has-key($nhsuk-grid-widths, $key) {
+    @return map.get($nhsuk-grid-widths, $key);
   }
 
   @error "Unknown grid width `#{$key}`";
 }
 
+/// Grid width percentage (alias)
+///
+/// @alias govuk-grid-width
+/// @deprecated To be removed in v10.0, replaced by govuk-grid-width
+
+@function grid-width($key) {
+  @return govuk-grid-width($key);
+}
+
 /// Generate grid row styles
 ///
 /// Creates a grid row class with a standardised margin.
 ///
-/// @param {String} $class [govuk-grid-row] CSS class name
+/// @param {String} $class [nhsuk-grid-row] CSS class name
 ///
 /// @example scss - Default
 ///   @include govuk-grid-row;
 ///
 /// @example scss - Customising the class name
 ///   @include govuk-grid-row("app-grid");
+///
+/// @deprecated To be removed in v10.0, replaced by the nhsuk-grid-row class
 
 @mixin govuk-grid-row($class: "nhsuk-grid-row") {
   .#{$class} {
     @include clearfix;
-    margin-left: -($nhsuk-gutter-half);
     margin-right: -($nhsuk-gutter-half);
+    margin-left: -($nhsuk-gutter-half);
   }
 }
 
 /// Generate grid column styles
 ///
-/// Creates a cross browser grid column with a class of '.govuk-grid-column' by
-/// default, and a standardised gutter between the columns.
+/// Creates a grid column with standard gutter between the columns.
+///
+/// If a `$class` is provided (which is the default, but deprecated behaviour),
+/// the generated rules will be wrapped in a predefined selector in the format
+/// `$class-$width` (e.g. `nhsuk-grid-column-full`). This behaviour is
+/// deprecated and will be removed in v10.0
 ///
-/// Common widths are predefined above as keywords in the `$grid-widths` map.
+/// Grid widths are defined in the `$nhsuk-grid-widths` map.
 ///
-/// By default their width changes from 100% to specified width at the 'tablet'
-/// breakpoint, but that can be configured to be any other breakpoint by using
-/// the `$at` parameter.
+/// By default the column width changes from 100% to specified width at the
+/// 'desktop' breakpoint, but other breakpoints can be specified using the `$at`
+/// parameter.
 ///
-/// @param {String} $class [govuk-grid-column] CSS class name
-/// @param {String} $width [full] one-quarter | one-third | one-half | two-third | three-quarters | full
+/// @param {String} $width [full] name of a grid width from $nhsuk-grid-widths
 /// @param {String} $float [left] left | right
-/// @param {String} $at [tablet] - mobile | tablet | desktop | any custom breakpoint in px or em
+/// @param {String} $at [desktop] - mobile | tablet | desktop | any custom breakpoint
+/// @param {String} $class [nhsuk-grid-column] CSS class name (deprecated)
 ///
 /// @example scss - Default
-///   @include govuk-grid-column(two-thirds)
-///
-/// @example scss - Customising the class name
-///   @include govuk-grid-column(one-half, $class: "test-column");
+///   .nhsuk-grid-column-two-thirds {
+///     @include govuk-grid-column(two-thirds, $class: false)
+///   }
 ///
 /// @example scss - Customising the breakpoint where width percentage is applied
-///   @include govuk-grid-column(one-half, $at: desktop);
+///   .nhsuk-grid-column-one-half-at-tablet {
+///     @include govuk-grid-column(one-half, $at: tablet);
+///   }
 ///
 /// @example scss - Customising the float direction
-///   @include govuk-grid-column(one-half, $float: right);
+///   .nhsuk-grid-column-one-half-right {
+///     @include govuk-grid-column(two-thirds, $float: right, $class: false);
+///   }
+///
+/// @example scss - Customising the class name (deprecated)
+///   @include govuk-grid-column(one-half, $class: "test-column");
+///
+/// @access public
 
 @mixin govuk-grid-column($width: full, $float: left, $at: desktop, $class: "nhsuk-grid-column") {
-  .#{$class}-#{$width} {
+  @if $class {
+    .#{$class}-#{$width} {
+      @include govuk-grid-column($width, $float, $at, $class: false);
+    }
+  } @else {
     box-sizing: border-box;
-    padding: 0 $nhsuk-gutter-half;
-    @if $at != desktop {
+    @if $at != tablet {
       width: 100%;
     }
+    padding: 0 $nhsuk-gutter-half;
     @include govuk-media-query($from: $at) {
+      width: govuk-grid-width($width);
       float: $float;
-      width: grid-width($width);
     }
   }
 }