diff --git a/CHANGELOG.md b/CHANGELOG.md index eb8afbd5f0..9b0fb76ab7 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/packages/govuk-frontend/src/govuk/_base.scss b/packages/govuk-frontend/src/govuk/_base.scss index c9543ab860..937ebccb6d 100644 --- a/packages/govuk-frontend/src/govuk/_base.scss +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/all.scss b/packages/govuk-frontend/src/govuk/all.scss index 96972b724f..6cea767686 100644 --- a/packages/govuk-frontend/src/govuk/all.scss +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/all.unit.test.mjs b/packages/govuk-frontend/src/govuk/all.unit.test.mjs index c8efa775fd..aa237de637 100644 --- a/packages/govuk-frontend/src/govuk/all.unit.test.mjs +++ b/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() + ) + ) + ) + }) + }) }) diff --git a/packages/govuk-frontend/src/govuk/components/_all.scss b/packages/govuk-frontend/src/govuk/components/_all.scss index ae246e4950..d215b79840 100644 --- a/packages/govuk-frontend/src/govuk/components/_all.scss +++ b/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 +); diff --git a/packages/govuk-frontend/src/govuk/components/_index.scss b/packages/govuk-frontend/src/govuk/components/_index.scss new file mode 100644 index 0000000000..ae246e4950 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/core/_all.scss b/packages/govuk-frontend/src/govuk/core/_all.scss index 48e95beaf5..371baa08c4 100644 --- a/packages/govuk-frontend/src/govuk/core/_all.scss +++ b/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 +); diff --git a/packages/govuk-frontend/src/govuk/core/_index.scss b/packages/govuk-frontend/src/govuk/core/_index.scss new file mode 100644 index 0000000000..48e95beaf5 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/helpers/_all.scss b/packages/govuk-frontend/src/govuk/helpers/_all.scss index b3b280a625..256cfcf520 100644 --- a/packages/govuk-frontend/src/govuk/helpers/_all.scss +++ b/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 +); diff --git a/packages/govuk-frontend/src/govuk/helpers/_index.scss b/packages/govuk-frontend/src/govuk/helpers/_index.scss new file mode 100644 index 0000000000..b3b280a625 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/index.scss b/packages/govuk-frontend/src/govuk/index.scss new file mode 100644 index 0000000000..6cea767686 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/objects/_all.scss b/packages/govuk-frontend/src/govuk/objects/_all.scss index 13f47f0565..5085b3b46c 100644 --- a/packages/govuk-frontend/src/govuk/objects/_all.scss +++ b/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 +); diff --git a/packages/govuk-frontend/src/govuk/objects/_index.scss b/packages/govuk-frontend/src/govuk/objects/_index.scss new file mode 100644 index 0000000000..13f47f0565 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/overrides/_all.scss b/packages/govuk-frontend/src/govuk/overrides/_all.scss index 7e475f3c6f..2b6d744826 100644 --- a/packages/govuk-frontend/src/govuk/overrides/_all.scss +++ b/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'." +); diff --git a/packages/govuk-frontend/src/govuk/overrides/_index.scss b/packages/govuk-frontend/src/govuk/overrides/_index.scss new file mode 100644 index 0000000000..7e475f3c6f --- /dev/null +++ b/packages/govuk-frontend/src/govuk/overrides/_index.scss @@ -0,0 +1,5 @@ +@import "display"; +@import "spacing"; +@import "text-align"; +@import "typography"; +@import "width"; diff --git a/packages/govuk-frontend/src/govuk/settings/_all.scss b/packages/govuk-frontend/src/govuk/settings/_all.scss index fb25212fa3..4dfed42e9e 100644 --- a/packages/govuk-frontend/src/govuk/settings/_all.scss +++ b/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 +); diff --git a/packages/govuk-frontend/src/govuk/settings/_index.scss b/packages/govuk-frontend/src/govuk/settings/_index.scss new file mode 100644 index 0000000000..fb25212fa3 --- /dev/null +++ b/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"; diff --git a/packages/govuk-frontend/src/govuk/settings/_warnings.scss b/packages/govuk-frontend/src/govuk/settings/_warnings.scss index 6a63fcf13b..39478b147f 100644 --- a/packages/govuk-frontend/src/govuk/settings/_warnings.scss +++ b/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; + } } } diff --git a/packages/govuk-frontend/src/govuk/settings/warnings.unit.test.js b/packages/govuk-frontend/src/govuk/settings/warnings.unit.test.js index 2548833a2b..976846d769 100644 --- a/packages/govuk-frontend/src/govuk/settings/warnings.unit.test.js +++ b/packages/govuk-frontend/src/govuk/settings/warnings.unit.test.js @@ -46,6 +46,18 @@ describe('Warnings mixin', () => { expect(mockWarnFunction.mock.calls).toHaveLength(1) }) + it('fires every @warn if $silence-further-warnings is false', async () => { + const sass = ` + ${sassBootstrap} + @include _warning('test', 'This is a warning.', $silence-further-warnings: false); + @include _warning('test', 'This is a warning.'); + ` + + await compileSassString(sass, sassConfig) + + expect(mockWarnFunction.mock.calls).toHaveLength(2) + }) + it('Does not fire a @warn if the key is already in $govuk-suppressed-warnings', async () => { const sass = ` ${sassBootstrap} diff --git a/packages/govuk-frontend/src/govuk/tools/_all.scss b/packages/govuk-frontend/src/govuk/tools/_all.scss index 69d4bf0d63..b8f40aeede 100644 --- a/packages/govuk-frontend/src/govuk/tools/_all.scss +++ b/packages/govuk-frontend/src/govuk/tools/_all.scss @@ -1,5 +1,8 @@ -@import "exports"; -@import "font-url"; -@import "image-url"; -@import "px-to-em"; -@import "px-to-rem"; +@import "../settings/warnings"; +@import "index"; + +@include _warning( + "import-using-all", + "Importing using 'govuk/tools/all' is deprecated. Update your import statement to import 'govuk/tools/index'.", + $silence-further-warnings: false +); diff --git a/packages/govuk-frontend/src/govuk/tools/_index.scss b/packages/govuk-frontend/src/govuk/tools/_index.scss new file mode 100644 index 0000000000..69d4bf0d63 --- /dev/null +++ b/packages/govuk-frontend/src/govuk/tools/_index.scss @@ -0,0 +1,5 @@ +@import "exports"; +@import "font-url"; +@import "image-url"; +@import "px-to-em"; +@import "px-to-rem"; diff --git a/packages/govuk-frontend/src/govuk/utilities/_all.scss b/packages/govuk-frontend/src/govuk/utilities/_all.scss index 5bed0f775f..564e9f5f55 100644 --- a/packages/govuk-frontend/src/govuk/utilities/_all.scss +++ b/packages/govuk-frontend/src/govuk/utilities/_all.scss @@ -1,2 +1,8 @@ -@import "clearfix"; -@import "visually-hidden"; +@import "../settings/warnings"; +@import "index"; + +@include _warning( + "import-using-all", + "Importing using 'govuk/utilities/all' is deprecated. Update your import statement to import 'govuk/utilities/index'.", + $silence-further-warnings: false +); diff --git a/packages/govuk-frontend/src/govuk/utilities/_index.scss b/packages/govuk-frontend/src/govuk/utilities/_index.scss new file mode 100644 index 0000000000..5bed0f775f --- /dev/null +++ b/packages/govuk-frontend/src/govuk/utilities/_index.scss @@ -0,0 +1,2 @@ +@import "clearfix"; +@import "visually-hidden";