[node-build-scripts] feat: use non-legacy Sass compiler, remove node-…

…sass (#5904)

packages/core/package.json

@@ -27,7 +27,7 @@
         "compile:esm": "tsc -p ./src",
         "compile:cjs": "tsc -p ./src -m commonjs --outDir lib/cjs",
         "compile:esnext": "tsc -p ./src -t esnext --outDir lib/esnext",
-        "compile:css": "sass-compile --functions ./scripts/sass-custom-functions.js ./src",
+        "compile:css": "sass-compile ./src",
         "dev": "run-p \"compile:esm -- --watch\" \"compile:css -- --watch\"",
         "dist": "run-s \"dist:*\"",
         "dist:bundle": "cross-env NODE_ENV=production webpack",
@@ -73,7 +73,6 @@
         "@blueprintjs/node-build-scripts": "^6.0.7",
         "@blueprintjs/test-commons": "^1.1.9",
         "@testing-library/react": "^12.1.5",
-        "@vgrid/sass-inline-svg": "^1.0.1",
         "enzyme": "^3.11.0",
         "karma": "^6.4.1",
         "mocha": "^10.1.0",

packages/core/src/blueprint.scss

@@ -6,7 +6,7 @@ Licensed under the Apache License, Version 2.0.
 */
 
 // Import files in the same order that they are documented in the docs
-@import "~@blueprintjs/colors/lib/scss/colors";
+@import "@blueprintjs/colors/lib/scss/colors";
 @import "common/variables";
 @import "common/variables-extended";
 @import "common/mixins";

packages/core/src/common/_mixins.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @use "sass:math";
-@import "~@blueprintjs/colors/lib/scss/colors";
+@import "@blueprintjs/colors/lib/scss/colors";
 @import "flex";
 
 $pt-intent-colors: (

packages/core/src/common/_variables-extended.scss

@@ -3,10 +3,11 @@
 
 @import "variables";
 
-// This file contains additional common variables which we do not want to export
-// in public API via variables.scss, or they contain syntax which does not play
-// well with our generate-css-variables script and thus cannot be easily
+// ----------------------------------------------------------------------------
+// This file contains additional common variables which we do not want to export in public API via variables.scss,
+// or they contain syntax which does not parse easily with our generate-css-variables script and thus cannot be easily
 // exported.
+// ----------------------------------------------------------------------------
 
 $half-grid-size: $pt-grid-size * 0.5 !default;
 

packages/core/src/common/_variables.scss

@@ -5,6 +5,15 @@
 @import "color-aliases";
 @import "mixins";
 
+// ----------------------------------------------------------------------------
+// This file contains most of the public Sass API of @blueprintjs/core.
+// As such, it comes with important considerations:
+//
+// -  Changes to these variable names and values are generally considered breaking changes.
+// -  A limited subset of Sass syntax is supported. All syntax inluded here must be able to get parsed by the
+//    `generate-css-variables` script in @blueprintjs/node-build-scripts.
+// ----------------------------------------------------------------------------
+
 // Namespace appended to the beginning of each CSS class: `.#{$ns}-button`.
 // N.B. No quotes around this string value, for Less syntax compatibility. Also, this cannot be overriden
 // (the JS components have this class prefix hard-coded), so it does not have the `!default` modifier.
@@ -46,10 +55,12 @@ $pt-font-size-large: $pt-grid-size * 1.6 !default;
 $pt-font-size-small: $pt-grid-size * 1.2 !default;
 
 // a little bit extra to ensure the height comes out to just over 18px (and browser rounds to 18px)
+// equivalent to: 1.28581
 $pt-line-height: math.div($pt-grid-size * 1.8, $pt-font-size) + 0.0001 !default;
 
 // Grids & dimensions
 
+// equivalent to: 2px
 $pt-border-radius: floor(math.div($pt-grid-size, 5)) !default;
 
 // Buttons

packages/core/src/components/breadcrumbs/_breadcrumbs.scss

@@ -1,7 +1,7 @@
 // Copyright 2016 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/variables";
 
 /*

packages/core/src/components/dialog/_dialog.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @use "sass:math";
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/mixins";
 @import "../../common/react-transition";
 @import "../../common/variables";

packages/core/src/components/dialog/_multistep-dialog.scss

@@ -1,7 +1,7 @@
 // Copyright 2020 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/mixins";
 @import "../../common/react-transition";
 @import "../../common/variables";

packages/core/src/components/drawer/_drawer.scss

@@ -1,7 +1,7 @@
 // Copyright 2018 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/mixins";
 @import "../../common/react-transition";
 @import "../../common/variables";

packages/core/src/components/forms/_common.scss

@@ -1,7 +1,7 @@
 // Copyright 2015 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/variables";
 @import "../button/common";
 

packages/core/src/components/icon/_icon-mixins.scss

@@ -1,7 +1,7 @@
 // Copyright 2021 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/colors/lib/scss/colors";
+@import "@blueprintjs/colors/lib/scss/colors";
 
 @mixin pt-icon-font-smoothing() {
   -moz-osx-font-smoothing: grayscale;

packages/core/src/components/icon/_icon.scss

@@ -1,7 +1,7 @@
 // Copyright 2015 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/variables";
 @import "../../common/variables-extended";
 @import "icon-mixins";

packages/core/src/components/menu/_menu.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @import "../../common/variables";
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/mixins";
 
 @import "./common";

packages/core/src/components/menu/_submenu.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @import "../../common/variables";
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "./common";
 
 .#{$ns}-submenu {

packages/core/src/components/panel-stack/_panel-stack.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @import "../../common/variables";
-@import "~@blueprintjs/core/src/common/react-transition";
+@import "@blueprintjs/core/src/common/react-transition";
 
 .#{$ns}-panel-stack {
   overflow: hidden;

packages/core/src/components/panel-stack2/_panel-stack2.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @import "../../common/variables";
-@import "~@blueprintjs/core/src/common/react-transition";
+@import "@blueprintjs/core/src/common/react-transition";
 
 .#{$ns}-panel-stack2 {
   overflow: hidden;

packages/core/src/components/slider/_common.scss

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 @import "../../common/variables";
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/mixins";
 @import "../button/common";
 

packages/core/src/components/tree/_tree.scss

@@ -1,7 +1,7 @@
 // Copyright 2015 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 @import "../../common/variables";
 @import "../../common/variables-extended";
 @import "../../common/mixins";

packages/core/src/docs/classes.md

@@ -39,7 +39,7 @@ import { Classes } from "@blueprintjs/core";
 ```scss
 // interpolate the $ns variable to generate forward-compatible class names.
 // this approach is *not encouraged* as it increases maintenance cost.
-@import "~@blueprintjs/core/lib/scss/variables";
+@import "@blueprintjs/core/lib/scss/variables";
 .#{$ns}-menu-item {
 }
 ```
@@ -76,18 +76,87 @@ can be used together on a single page.
 
 ### Custom namespace
 
-The namespace can be changed _at build time_ to produce a custom Blueprint build
-(though this usage is not recommended and we cannot offer support for it). This
-requires several things:
-
-1. You must use Sass and import Blueprint Sass source into your app, rather than using the CSS file distributed in the NPM package.
-    - Compiling Blueprint Sass source requires two additional tools:
-      [node-sass-package-importer](https://www.npmjs.com/package/node-sass-package-importer)
-      for resolving node_modules imports and
-      [sass-inline-svg](https://github.com/haithembelhaj/sass-inline-svg) for
-      inlining SVG images.
-1. Define the `$ns` Sass variable in your app styles before importing `blueprint.scss` to update the generated CSS.
-1. When bundling your code, set the `BLUEPRINT_NAMESPACE` environment variable to the same value to update the generated `Classes` constants. The easiest way to do this is on the command line: `BLUEPRINT_NAMESPACE="custom" webpack ...args`
+The CSS namespace can be changed _at build time_ to produce a custom Blueprint build.
+With this approach, you will import Blueprint's Sass sources from `/lib/scss/` instead of the CSS files from the
+`/lib/css/` folders.
+
+You must use [Dart Sass](https://sass-lang.com/dart-sass) and set up a few important bits of build configuration:
+
+1. Sass `loadPaths` must include the `node_modules` folder where `@blueprintjs` packages are installed
+1. A custom function implementation for `svg-icon()` must be defined
+1. You must copy the [resources/icons folder](https://github.com/palantir/blueprint/tree/develop/resources/icons) from
+    the Blueprint repo into your project (in the future, this may not be required once Blueprint starts publishing
+    these SVG files in a public NPM package).
+
+The __@blueprintjs/node-build-scripts__ package provides some utility functions to help with this. Here's a code example
+for a custom Sass compiler that can import Blueprint `.scss` sources:
+
+```js
+import { sassNodeModulesLoadPaths, sassSvgInlinerFactory } from "@blueprintjs/node-build-scripts";
+import sass from "sass";
+
+const result = await sass.compileAsync("path/to/input.scss", {
+    loadPaths: sassNodeModulesLoadPaths,
+    functions: {
+        /**
+         * Sass function to inline a UI icon svg and change its path color.
+         *
+         * Usage:
+         * svg-icon("16px/icon-name.svg", (path: (fill: $color)) )
+         */
+        "svg-icon($path, $selectors: null)": sassSvgInlinerFactory("path/to/resources/icons", {
+            optimize: true,
+            encodingFormat: "uri",
+        }),
+    },
+});
+```
+
+In addition to the JS API, you can specify this configuration with Webpack's sass-loader:
+
+```js
+// webpack.config.mjs
+
+import { sassNodeModulesLoadPaths, sassSvgInlinerFactory } from "@blueprintjs/node-build-scripts";
+import sass from "sass";
+
+const functions = {
+    /**
+     * Sass function to inline a UI icon svg and change its path color.
+     *
+     * Usage:
+     * svg-icon("16px/icon-name.svg", (path: (fill: $color)) )
+     */
+    "svg-icon($path, $selectors: null)": sassSvgInlinerFactory("path/to/resources/icons", {
+        optimize: true,
+        encodingFormat: "uri",
+    }),
+};
+
+export default {
+    module: {
+        rules: [
+            {
+                test: /\.scss$/,
+                use: {
+                    loader: require.resolve("sass-loader"),
+                    options: {
+                        sassOptions: {
+                            loadPaths: sassNodeModulesLoadPaths,
+                            functions,
+                        },
+                    },
+                },
+            },
+        ],
+    },
+};
+```
+
+Once you have this build configuration set up, you can proceed to customize Sass and JS variables:
+
+1. Define the `$ns` Sass variable in your app styles _before_ importing `blueprint.scss`.
+1. When bundling your JS code, set the `BLUEPRINT_NAMESPACE` environment variable to the same value to update the generated `Classes` constants. The easiest way to do this is on the command line: `BLUEPRINT_NAMESPACE="custom" webpack ...args`
 
 @## Linting
 

packages/core/src/docs/colors.md

@@ -54,7 +54,7 @@ Blueprint provides variables for colors in Sass, Less, and JavaScript.
 Example in Sass:
 
 ```scss
-@import "~@blueprintjs/core/lib/scss/variables";
+@import "@blueprintjs/core/lib/scss/variables";
 
 .rule {
     color: $pt-link-color;
@@ -65,7 +65,7 @@ Example in Sass:
 Example in Less:
 
 ```less
-@import "~@blueprintjs/core/lib/less/variables";
+@import "@blueprintjs/core/lib/less/variables";
 
 .rule {
     color: @pt-link-color;

packages/core/src/docs/variables.md

@@ -42,7 +42,7 @@ variables in Sass as a map and in TypeScript as an object (see the [Icons sectio
 full list of identifiers):
 
 ```scss
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 
 .my-custom-icon {
     content: map-get($blueprint-icon-codepoints, "tick");

packages/datetime/src/_common.scss

@@ -1,9 +1,9 @@
 // Copyright 2017 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/colors/lib/scss/colors";
-@import "~@blueprintjs/core/src/common/variables";
-@import "~@blueprintjs/icons/lib/scss/variables";
+@import "@blueprintjs/colors/lib/scss/colors";
+@import "@blueprintjs/core/src/common/variables";
+@import "@blueprintjs/icons/lib/scss/variables";
 
 $datepicker-padding: $pt-grid-size * 0.5 !default;
 

packages/datetime/src/_datepicker.scss

@@ -1,8 +1,8 @@
 // Copyright 2015 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/colors/lib/scss/colors";
-@import "~@blueprintjs/core/src/components/popover/common";
+@import "@blueprintjs/colors/lib/scss/colors";
+@import "@blueprintjs/core/src/components/popover/common";
 @import "./common";
 
 $cell-size: $pt-grid-size * 3 !default;

packages/datetime/src/_timepicker.scss

@@ -1,8 +1,8 @@
 // Copyright 2015 Palantir Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0.
 
-@import "~@blueprintjs/core/src/components/forms/common";
-@import "~@blueprintjs/core/src/components/icon/icon-mixins";
+@import "@blueprintjs/core/src/components/forms/common";
+@import "@blueprintjs/core/src/components/icon/icon-mixins";
 @import "./common";
 
 $timepicker-input-row-height: $pt-grid-size * 3 !default;