From 058337b301555da33a71ccc2dca659c98cc5f6d1 Mon Sep 17 00:00:00 2001 From: "Dan O. Williams" <11464021+thisisdano@users.noreply.github.com> Date: Sun, 5 Jan 2025 00:50:52 -0800 Subject: [PATCH 1/5] Use gulp-sass 6.0 --- package-lock.json | 9 ++++----- package.json | 2 +- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/package-lock.json b/package-lock.json index 36229ed..cbb936e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -15,7 +15,7 @@ "gulp-postcss": "9.0.1", "gulp-rename": "2.0.0", "gulp-replace": "1.1.4", - "gulp-sass": "5.1.0", + "gulp-sass": "6.0.0", "gulp-svgstore": "9.0.0", "postcss": "8.4.49", "postcss-csso": "6.0.1", @@ -1446,10 +1446,9 @@ } }, "node_modules/gulp-sass": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/gulp-sass/-/gulp-sass-5.1.0.tgz", - "integrity": "sha512-7VT0uaF+VZCmkNBglfe1b34bxn/AfcssquLKVDYnCDJ3xNBaW7cUuI3p3BQmoKcoKFrs9jdzUxyb+u+NGfL4OQ==", - "license": "MIT", + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/gulp-sass/-/gulp-sass-6.0.0.tgz", + "integrity": "sha512-FGb4Uab4jnH2GnSfBGd6uW3+imvNodAGfsjGcUhEtpNYPVx+TK2tp5uh7MO0sSR7aIf1Sm544werc+zV7ejHHw==", "dependencies": { "lodash.clonedeep": "^4.5.0", "picocolors": "^1.0.0", diff --git a/package.json b/package.json index 3c0f273..c25aae5 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,7 @@ "gulp-postcss": "9.0.1", "gulp-rename": "2.0.0", "gulp-replace": "1.1.4", - "gulp-sass": "5.1.0", + "gulp-sass": "6.0.0", "gulp-svgstore": "9.0.0", "postcss": "8.4.49", "postcss-csso": "6.0.1", From 752dcd6c7fdf8a7baeabb2600ab881b7d86b2aa6 Mon Sep 17 00:00:00 2001 From: "Dan O. Williams" <11464021+thisisdano@users.noreply.github.com> Date: Sun, 5 Jan 2025 00:51:07 -0800 Subject: [PATCH 2/5] Use modern Sass API --- gulpfile.js | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/gulpfile.js b/gulpfile.js index 577bf93..3c0a687 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -66,7 +66,7 @@ let settings = { }, browserslist: ["> 2%", "last 2 versions", "IE 11", "not dead"], sassSourcemaps: true, - sassDeprecationWarnings: false + sassDeprecationWarnings: false, }, sprite: { width: 24, @@ -123,9 +123,7 @@ const copy = { ); return src(`${getSrcFrom("img")}/**/**`.replace("//", "/"), { encoding: false, - }).pipe( - dest(paths.dist.img) - ); + }).pipe(dest(paths.dist.img)); }, js() { log( @@ -197,8 +195,8 @@ function buildSass() { }) .pipe( sass({ - outputStyle: "compressed", - includePaths: buildSettings.includes, + style: "compressed", + loadPaths: buildSettings.includes, quietDeps: !settings.compile.sassDeprecationWarnings, }).on("error", handleError) ) @@ -256,7 +254,7 @@ function buildSprite() { return src(spritePaths, { allowEmpty: true, - encoding: false + encoding: false, }) .pipe(svgSprite()) .pipe(rename("usa-icons.svg")) @@ -267,7 +265,7 @@ function buildSprite() { function renameSprite() { return src(`${paths.dist.img}/usa-icons.svg`.replace("//", "/"), { allowEmpty: true, - encoding: false + encoding: false, }) .pipe(rename(`${paths.dist.img}/sprite.svg`.replace("//", "/"))) .pipe(dest(`./`)); From 8f44741987a8ddbf950d522db814342f77491923 Mon Sep 17 00:00:00 2001 From: Matt Mower Date: Wed, 5 Feb 2025 16:34:59 -0800 Subject: [PATCH 3/5] Support sass-embedded options - Add `sassOptions` to `settings.compile`. - Include type hints from `sass-embedded` Options. Until `@types/gulp-sass` is updated for v6, this is more correct than using `GulpSassOptions` from `@types/gulp-sass` which is based on `node-sass`. - Indicate default options that will apply unless overridden. - Deprecate (but still support) `sassDeprecationWarnings`. - Include JSDoc deprecation notice. - Better support SASS option `style` when set to `expanded` to avoid running CSSO minification. This improves source map reliability. --- README.md | 12 ++++++------ gulpfile.js | 29 +++++++++++++++++++++++++---- 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a969db7..828cd74 100644 --- a/README.md +++ b/README.md @@ -96,12 +96,12 @@ Use path settings to customize where USWDS Compile looks for USWDS source and ou ### Additional settings -| Setting | Default | Description | -| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. | -| `settings.compile.browserslist` | `["> 2%", "last 2 versions", "IE 11", "not dead"]` | Define the [browserslist query](https://github.com/browserslist/browserslist?tab=readme-ov-file#queries) for CSS prefixes generated by [autoprefixer](https://github.com/postcss/autoprefixer). | -| `settings.compile.sassSourcemaps` | `true` | Include sourcemap when compiling SASS to CSS. | -| `settings.compile.sassDeprecationWarnings` | `false` | Show USWDS Sass deprecation warnings. When set to `true`, Sass will output deprecation warnings for USWDS code in the terminal during compilation. Deprecation warnings for non-USWDS Sass will output even when this value is set to `false`. | +| Setting | Default | Description | +| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. | +| `settings.compile.browserslist` | `["> 2%", "last 2 versions", "IE 11", "not dead"]` | Define the [browserslist query](https://github.com/browserslist/browserslist?tab=readme-ov-file#queries) for CSS prefixes generated by [autoprefixer](https://github.com/postcss/autoprefixer). | +| `settings.compile.sassSourcemaps` | `true` | Include sourcemap when compiling SASS to CSS. | +| `settings.compile.sassOptions` | `{quietDeps: true, style: "compressed"}` | Configure [sass-embedded options](https://sass-lang.com/documentation/js-api/interfaces/options/). By default SASS deprecation warnings arising from USWDS source are hidden and output CSS is minified. These options can be overriden and additional options specified. When `loadPaths` is defined, the paths are appended to those necessary for USWDS compilation. | ### Functions diff --git a/gulpfile.js b/gulpfile.js index 3c0a687..ee6aa16 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -66,7 +66,19 @@ let settings = { }, browserslist: ["> 2%", "last 2 versions", "IE 11", "not dead"], sassSourcemaps: true, - sassDeprecationWarnings: false, + /** + * @type {boolean | undefined} + * @deprecated Set `sassOptions.quietDeps` instead. */ + sassDeprecationWarnings: undefined, + /** + * @type {import('sass-embedded').Options<"async">} + * @default + * { + * quietDeps: true, + * style: "compressed" + * } + */ + sassOptions: {}, }, sprite: { width: 24, @@ -176,7 +188,9 @@ function buildSass() { grid: true, overrideBrowserslist: settings.compile.browserslist, }), - csso({ forceMediaMerge: false }), + ...(settings.compile.sassOptions.style === "expanded" + ? [] + : [csso({ forceMediaMerge: false })]), ], includes: [ // 1. local theme files @@ -196,8 +210,15 @@ function buildSass() { .pipe( sass({ style: "compressed", - loadPaths: buildSettings.includes, - quietDeps: !settings.compile.sassDeprecationWarnings, + ...settings.compile.sassOptions, + loadPaths: [ + ...buildSettings.includes, + ...(settings.compile.sassOptions.loadPaths ?? []), + ], + quietDeps: + settings.compile.sassDeprecationWarnings !== undefined + ? !settings.compile.sassDeprecationWarnings + : settings.compile.sassOptions.quietDeps ?? true, }).on("error", handleError) ) .pipe(replace(/\buswds @version\b/g, `based on uswds v${pkg}`)) From f02f12990241e578301bd1b8658fb611df624e73 Mon Sep 17 00:00:00 2001 From: Matt Mower Date: Mon, 10 Feb 2025 18:20:48 -0800 Subject: [PATCH 4/5] (Revisions) Support sass-embedded options - Watch `loadPaths` for changes. --- README.md | 12 ++++++------ gulpfile.js | 3 +++ 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 828cd74..83bfe71 100644 --- a/README.md +++ b/README.md @@ -96,12 +96,12 @@ Use path settings to customize where USWDS Compile looks for USWDS source and ou ### Additional settings -| Setting | Default | Description | -| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. | -| `settings.compile.browserslist` | `["> 2%", "last 2 versions", "IE 11", "not dead"]` | Define the [browserslist query](https://github.com/browserslist/browserslist?tab=readme-ov-file#queries) for CSS prefixes generated by [autoprefixer](https://github.com/postcss/autoprefixer). | -| `settings.compile.sassSourcemaps` | `true` | Include sourcemap when compiling SASS to CSS. | -| `settings.compile.sassOptions` | `{quietDeps: true, style: "compressed"}` | Configure [sass-embedded options](https://sass-lang.com/documentation/js-api/interfaces/options/). By default SASS deprecation warnings arising from USWDS source are hidden and output CSS is minified. These options can be overriden and additional options specified. When `loadPaths` is defined, the paths are appended to those necessary for USWDS compilation. | +| Setting | Default | Description | +| --------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `sprite.projectIconsOnly` | `false` | Include _only_ the icons in `paths.src.projectIcons` in the icon sprite. | +| `settings.compile.browserslist` | `["> 2%", "last 2 versions", "IE 11", "not dead"]` | Define the [browserslist query](https://github.com/browserslist/browserslist?tab=readme-ov-file#queries) for CSS prefixes generated by [autoprefixer](https://github.com/postcss/autoprefixer). | +| `settings.compile.sassSourcemaps` | `true` | Include sourcemap when compiling SASS to CSS. | +| `settings.compile.sassOptions` | `{quietDeps: true, style: "compressed"}` | Configure [sass-embedded options](https://sass-lang.com/documentation/js-api/interfaces/options/). By default SASS deprecation warnings arising from USWDS source are hidden and output CSS is minified. These options can be overridden and additional options specified. When `loadPaths` is defined, the paths are appended to those necessary for USWDS compilation. The `watch` script will also watch these directories for changes. | ### Functions diff --git a/gulpfile.js b/gulpfile.js index ee6aa16..4490c8d 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -235,6 +235,9 @@ function watchSass() { [ `${paths.dist.theme}/**/*.scss`.replace("//", "/"), `${paths.src.projectSass}/**/*.scss`.replace("//", "/"), + ...(settings.compile.sassOptions.loadPaths ?? []).map((loadPath) => + `${loadPath}/**/*.scss`.replace("//", "/") + ), ], buildSass ); From d1b7ae67cf66b654c7b42148b82cd16ea48742f0 Mon Sep 17 00:00:00 2001 From: Matt Mower Date: Mon, 15 Dec 2025 12:38:50 -0800 Subject: [PATCH 5/5] Update to gulp-sass v6.0.1 --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 644b69b..b084ba1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,7 +14,7 @@ "gulp-postcss": "9.0.1", "gulp-rename": "2.0.0", "gulp-replace": "1.1.4", - "gulp-sass": "6.0.0", + "gulp-sass": "6.0.1", "gulp-svgstore": "9.0.0", "postcss": "8.5.2", "postcss-csso": "6.0.1", @@ -1260,9 +1260,9 @@ } }, "node_modules/gulp-sass": { - "version": "6.0.0", - "resolved": "https://registry.npmjs.org/gulp-sass/-/gulp-sass-6.0.0.tgz", - "integrity": "sha512-FGb4Uab4jnH2GnSfBGd6uW3+imvNodAGfsjGcUhEtpNYPVx+TK2tp5uh7MO0sSR7aIf1Sm544werc+zV7ejHHw==", + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/gulp-sass/-/gulp-sass-6.0.1.tgz", + "integrity": "sha512-4wonidxB8lGPHvahelpGavUBJAuERSl+OIVxPCyQthK4lSJhZ/u3/qjFcyAtnMIXDl6fXTn34H4BXsN7gt54kQ==", "license": "MIT", "dependencies": { "lodash.clonedeep": "^4.5.0", diff --git a/package.json b/package.json index 580b168..6e15ad0 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,7 @@ "gulp-postcss": "9.0.1", "gulp-rename": "2.0.0", "gulp-replace": "1.1.4", - "gulp-sass": "6.0.0", + "gulp-sass": "6.0.1", "gulp-svgstore": "9.0.0", "postcss": "8.5.2", "postcss-csso": "6.0.1",