Merge pull request #4955 from alphagov/rename-all-to-index

Rename `all` files to `index` for our Sass entrypoints

CHANGELOG.md

@@ -4,6 +4,27 @@ For advice on how to use these release notes see [our guidance on staying up to
 
 ## Unreleased
 
+### Deprecations
+
+#### Importing layers using `all` files
+
+You'll see a warning when compiling your Sass if you import any of our layers using the `all` file. Importing using the `all` files is deprecated, and we will remove them in the next major release.
+
+Update your import statements to refer to the `index` file for each layer rather than `all`:
+
+```scss
+@import "node_modules/govuk-frontend/dist/govuk/base";
+@import "node_modules/govuk-frontend/dist/govuk/core/index";
+@import "node_modules/govuk-frontend/dist/govuk/objects/index";
+@import "node_modules/govuk-frontend/dist/govuk/components/index";
+@import "node_modules/govuk-frontend/dist/govuk/utilities/index";
+@import "node_modules/govuk-frontend/dist/govuk/overrides/index";
+```
+
+You do not need `/index` at the end of each import path if you’re using Dart Sass, LibSass 3.6.0 or higher, or Ruby Sass 3.6.0 or higher.
+
+This change was introduced in [pull request #4955: Rename `all` files to `index` for our Sass entrypoints](https://github.com/alphagov/govuk-frontend/pull/4955).
+
 ### Fixes
 
 We've made fixes to GOV.UK Frontend in the following pull requests:

packages/govuk-frontend/src/govuk/_base.scss

@@ -1,3 +1,3 @@
-@import "settings/all";
-@import "tools/all";
-@import "helpers/all";
+@import "settings/index";
+@import "tools/index";
+@import "helpers/index";

packages/govuk-frontend/src/govuk/all.scss

@@ -1,9 +1,9 @@
 @import "base";
 
-@import "core/all";
-@import "objects/all";
+@import "core/index";
+@import "objects/index";
 
-@import "components/all";
+@import "components/index";
 
-@import "utilities/all";
-@import "overrides/all";
+@import "utilities/index";
+@import "overrides/index";

packages/govuk-frontend/src/govuk/all.unit.test.mjs

@@ -1,8 +1,11 @@
 import { paths } from '@govuk-frontend/config'
 import { compileSassString } from '@govuk-frontend/helpers/tests'
+import { sassNull } from 'sass-embedded'
 import sassdoc from 'sassdoc'
 import slash from 'slash'
 
+let mockWarnFunction, sassConfig
+
 describe('GOV.UK Frontend', () => {
   describe('global styles', () => {
     it('are disabled by default', async () => {
@@ -97,4 +100,56 @@ describe('GOV.UK Frontend', () => {
         )
     })
   })
+
+  describe('importing using "all" files', () => {
+    beforeAll(() => {
+      // Create a mock warn function that we can use to override the native @warn
+      // function, that we can make assertions about post-render.
+      mockWarnFunction = jest.fn().mockReturnValue(sassNull)
+
+      sassConfig = {
+        logger: {
+          warn: mockWarnFunction
+        }
+      }
+    })
+
+    it('outputs a warning for each layer that has an "all" file', async () => {
+      const sass = `
+      /* equivalent to importing 'base' */
+      @import "settings/all";
+      @import "tools/all";
+      @import "helpers/all";
+
+      @import "core/all";
+      @import "objects/all";
+
+      @import "components/all";
+
+      @import "utilities/all";
+      @import "overrides/all";
+      `
+
+      await compileSassString(sass, sassConfig)
+
+      return Promise.all(
+        [
+          'settings',
+          'tools',
+          'helpers',
+          'core',
+          'objects',
+          'components',
+          'utilities',
+          'overrides'
+        ].map((section, index) =>
+          expect(mockWarnFunction).toHaveBeenNthCalledWith(
+            index + 1,
+            `Importing using 'govuk/${section}/all' is deprecated. Update your import statement to import 'govuk/${section}/index'. To silence this warning, update $govuk-suppressed-warnings with key: "import-using-all"`,
+            expect.anything()
+          )
+        )
+      )
+    })
+  })
 })

packages/govuk-frontend/src/govuk/components/_all.scss

@@ -1,37 +1,8 @@
-@import "../base";
+@import "../settings/warnings";
+@import "index";
 
-@import "accordion/index";
-@import "back-link/index";
-@import "breadcrumbs/index";
-@import "button/index";
-@import "character-count/index";
-@import "checkboxes/index";
-@import "cookie-banner/index";
-@import "date-input/index";
-@import "details/index";
-@import "error-message/index";
-@import "error-summary/index";
-@import "exit-this-page/index";
-@import "fieldset/index";
-@import "file-upload/index";
-@import "footer/index";
-@import "header/index";
-@import "hint/index";
-@import "input/index";
-@import "inset-text/index";
-@import "label/index";
-@import "notification-banner/index";
-@import "pagination/index";
-@import "panel/index";
-@import "password-input/index";
-@import "phase-banner/index";
-@import "radios/index";
-@import "select/index";
-@import "skip-link/index";
-@import "summary-list/index";
-@import "table/index";
-@import "tabs/index";
-@import "tag/index";
-@import "task-list/index";
-@import "textarea/index";
-@import "warning-text/index";
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/components/all' is deprecated. Update your import statement to import 'govuk/components/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/components/_index.scss

@@ -0,0 +1,37 @@
+@import "../base";
+
+@import "accordion/index";
+@import "back-link/index";
+@import "breadcrumbs/index";
+@import "button/index";
+@import "character-count/index";
+@import "checkboxes/index";
+@import "cookie-banner/index";
+@import "date-input/index";
+@import "details/index";
+@import "error-message/index";
+@import "error-summary/index";
+@import "exit-this-page/index";
+@import "fieldset/index";
+@import "file-upload/index";
+@import "footer/index";
+@import "header/index";
+@import "hint/index";
+@import "input/index";
+@import "inset-text/index";
+@import "label/index";
+@import "notification-banner/index";
+@import "pagination/index";
+@import "panel/index";
+@import "password-input/index";
+@import "phase-banner/index";
+@import "radios/index";
+@import "select/index";
+@import "skip-link/index";
+@import "summary-list/index";
+@import "table/index";
+@import "tabs/index";
+@import "tag/index";
+@import "task-list/index";
+@import "textarea/index";
+@import "warning-text/index";

packages/govuk-frontend/src/govuk/core/_all.scss

@@ -1,6 +1,8 @@
-@import "govuk-frontend-properties";
-@import "links";
-@import "lists";
-@import "typography";
-@import "section-break";
-@import "global-styles";
+@import "../settings/warnings";
+@import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/core/all' is deprecated. Update your import statement to import 'govuk/core/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/core/_index.scss

@@ -0,0 +1,6 @@
+@import "govuk-frontend-properties";
+@import "links";
+@import "lists";
+@import "typography";
+@import "section-break";
+@import "global-styles";

packages/govuk-frontend/src/govuk/helpers/_all.scss

@@ -1,12 +1,8 @@
-@import "clearfix";
-@import "colour";
-@import "device-pixels";
-@import "focused";
-@import "font-faces";
-@import "grid";
-@import "links";
-@import "media-queries";
-@import "shape-arrow";
-@import "spacing";
-@import "typography";
-@import "visually-hidden";
+@import "../settings/warnings";
+@import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/helpers/all' is deprecated. Update your import statement to import 'govuk/helpers/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/helpers/_index.scss

@@ -0,0 +1,12 @@
+@import "clearfix";
+@import "colour";
+@import "device-pixels";
+@import "focused";
+@import "font-faces";
+@import "grid";
+@import "links";
+@import "media-queries";
+@import "shape-arrow";
+@import "spacing";
+@import "typography";
+@import "visually-hidden";

packages/govuk-frontend/src/govuk/index.scss

@@ -0,0 +1,9 @@
+@import "base";
+
+@import "core/index";
+@import "objects/index";
+
+@import "components/index";
+
+@import "utilities/index";
+@import "overrides/index";

packages/govuk-frontend/src/govuk/objects/_all.scss

@@ -1,6 +1,8 @@
-@import "button-group";
-@import "form-group";
-@import "grid";
-@import "main-wrapper";
-@import "template";
-@import "width-container";
+@import "../settings/warnings";
+@import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/objects/all' is deprecated. Update your import statement to import 'govuk/objects/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/objects/_index.scss

@@ -0,0 +1,6 @@
+@import "button-group";
+@import "form-group";
+@import "grid";
+@import "main-wrapper";
+@import "template";
+@import "width-container";

packages/govuk-frontend/src/govuk/overrides/_all.scss

@@ -1,5 +1,7 @@
-@import "display";
-@import "spacing";
-@import "text-align";
-@import "typography";
-@import "width";
+@import "../settings/warnings";
+@import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/overrides/all' is deprecated. Update your import statement to import 'govuk/overrides/index'."
+);

packages/govuk-frontend/src/govuk/overrides/_index.scss

@@ -0,0 +1,5 @@
+@import "display";
+@import "spacing";
+@import "text-align";
+@import "typography";
+@import "width";

packages/govuk-frontend/src/govuk/settings/_all.scss

@@ -1,21 +1,8 @@
-// The order we import settings in is important, as some settings files rely on
-// others
-
-@import "assets";
-
-@import "warnings";
-@import "global-styles";
-
-@import "media-queries";
-
-@import "colours-palette";
-@import "colours-organisations";
-@import "colours-applied";
-
-@import "spacing";
-@import "measurements";
-
-@import "typography-font";
-@import "typography-responsive";
-
-@import "links";
+@import "../settings/warnings";
+@import "index";
+
+@include _warning(
+  "import-using-all",
+  "Importing using 'govuk/settings/all' is deprecated. Update your import statement to import 'govuk/settings/index'.",
+  $silence-further-warnings: false
+);

packages/govuk-frontend/src/govuk/settings/_index.scss

@@ -0,0 +1,21 @@
+// The order we import settings in is important, as some settings files rely on
+// others
+
+@import "assets";
+
+@import "warnings";
+@import "global-styles";
+
+@import "media-queries";
+
+@import "colours-palette";
+@import "colours-organisations";
+@import "colours-applied";
+
+@import "spacing";
+@import "measurements";
+
+@import "typography-font";
+@import "typography-responsive";
+
+@import "links";

packages/govuk-frontend/src/govuk/settings/_warnings.scss

@@ -37,17 +37,22 @@ $govuk-suppressed-warnings: () !default;
 /// - To format the passed warning `$message` with the warning key at the end
 /// - To prevent duplicate warnings by adding the passed `$key` to
 /// `$govuk-suppressed-warnings` after `@warn` is called to ensure it only runs
-/// once per sass compilation
+/// once per sass compilation (unless $silence-further-warnings is false)
 ///
 /// @param {String} $key - The key to be checked against `$govuk-suppressed-warnings`
 /// and then passed to it to prevent multiple of the same warning.
 /// @param {String} $message - The message to use when calling `@warn`
+/// @param {Boolean} $silence-further-warnings - Whether to silence future
+/// warnings that use the same $key
 /// @access private
 
-@mixin _warning($key, $message) {
+@mixin _warning($key, $message, $silence-further-warnings: true) {
   @if _should-warn($key) {
     @warn _warning-text($key, $message);
-    $govuk-suppressed-warnings: append($govuk-suppressed-warnings, $key) !global;
+
+    @if $silence-further-warnings {
+      $govuk-suppressed-warnings: append($govuk-suppressed-warnings, $key) !global;
+    }
   }
 }