Create a single entrypoint for public sass API

UNRELEASED.md

@@ -24,3 +24,5 @@
 - Converted `ComboBox` to a functional component ([#2918](https://github.com/Shopify/polaris-react/pull/2918))
 
 ### Deprecations
+
+- Deprecated `styles/foundation.scss` and `styles/shared.scss` as entry points to the Polaris Sass public API. They have been replaced with a single file `styles/_public-api.scss`. By having a single entry point we make it a little easier for consuming applications to use our public API - you only need to import one file instead of two. Any references to these two files should be replaced with a reference to `_public-api.scss` which lives in the same folder. Consuming applications using sewing-kit should replace references to `esnext/styles/foundation.scss` and `esnext/styles/shared.scss` with a single reference to `esnext/styles/_public-api_.scss`. Note the API itself has not changed - only the mechanism by which you access it. ([#2974](https://github.com/Shopify/polaris-react/pull/2974))

config/rollup/plugins/styles.js

@@ -143,8 +143,8 @@ function generateMinifiedCss(sourceFilePath, css) {
  *   this base file.
  * - components.scss and the components folder: a suite of the compiled css for
  *  every component
- * - foundation.scss, shared.scss and the foundation and shared folders: our
- *   public Sass API.
+ * - _public-api.scss, foundation.scss, shared.scss and the foundation and
+ *  shared folders: our public Sass API.
  */
 async function generateSass(inputFolder, outputFolder, cssByFile) {
   // Copy contents of $inputFolder/styles/shared.scss and $inputFolder/styles/foundation.scss
@@ -185,8 +185,7 @@ async function generateSass(inputFolder, outputFolder, cssByFile) {
   const componentsScssContents = componentFilesContent.join('\n\n');
 
   // Generate polaris.scss
-  const polarisScssContent = `@import 'styles/foundation';
-@import 'styles/shared';
+  const polarisScssContent = `@import 'styles/public-api';
 @import 'styles/global';
 @import 'styles/components';
 `;

src/styles/_public-api.scss

@@ -0,0 +1,49 @@
+// This file is Polaris's public Sass API.
+// Consuming applications may import this file if they wish to use our helper functions
+//
+// In an app that does not use sewing-kit, import from a scss file:
+// `@import '~@shopify/polaris/styles/public-api';`
+//
+// In an app that uses sewing-kit >= 0.113.0 you can explicitly import
+// the esnext folder's public-api from a scss file:
+// `@import '~@shopify/polaris/esnext/styles/public-api';`
+// Or you can tell sewing-kit to automatically add that import to every scss
+// file by configuring the `autoInclude` option in sewing-kit's sass plugin
+// (assuming your sewing-kit.config.js is at the root of your repo):
+// plugins.sass({
+//   autoInclude: [
+//     path.join(__dirname, 'node_modules/@shopify/polaris/esnext/styles/_public-api.scss'),
+//   ],
+// }),
+
+// stylelint-disable scss/partial-no-import
+
+@import './foundation/utilities';
+@import './foundation/colors';
+@import './foundation/filters';
+@import './foundation/spacing';
+@import './foundation/border-width';
+@import './foundation/borders';
+@import './foundation/border-radius';
+@import './foundation/duration';
+@import './foundation/easing';
+@import './foundation/layout';
+@import './foundation/shadows';
+@import './foundation/typography';
+@import './foundation/z-index';
+@import './foundation/focus-ring';
+
+@import './shared/accessibility';
+@import './shared/breakpoints';
+@import './shared/buttons';
+@import './shared/controls';
+@import './shared/forms';
+@import './shared/icons';
+@import './shared/layout';
+@import './shared/links';
+@import './shared/lists';
+@import './shared/page';
+@import './shared/typography';
+@import './shared/skeleton';
+@import './shared/interaction-state';
+@import './shared/printing';

src/styles/foundation.scss

@@ -1,6 +1,13 @@
-// This file is part of Polaris's public Sass API.
-// Sewing Kit prepends every Component scss file with this file, making these
-// functions and mixins implicitly available.
+// This file is a deprecated part of Polaris's public Sass API.
+// Sewing Kit < 0.113.0 implicitly prepends every Component scss file with this
+// file (and shared.scss), making these functions and mixins implicitly available.
+// Sewing Kit 0.113.0 removed that implict functionality and instead requires
+// explict configuration. If you wish to use Polaris's public Sass API you
+// should explicitly import `_public-api.scss`
+// This file exists to maintain compatability with Sewing Kit < 0.113.0.
+// Any commits that modify this file's import list should also make the same
+// change in _public-api.scss
+// This file will be removed in Polaris v6.
 
 @import './foundation/utilities';
 @import './foundation/colors';

src/styles/shared.scss

@@ -1,6 +1,13 @@
-// This file is part of Polaris's public Sass API.
-// Sewing Kit prepends every Component scss file with this file, making these
-// functions and mixins implicitly available.
+// This file is a deprecated part of Polaris's public Sass API.
+// Sewing Kit < 0.113.0 implicitly prepends every Component scss file with this
+// file (and foundation.scss), making these functions and mixins implicitly available.
+// Sewing Kit 0.113.0 removed that implict functionality and instead requires
+// explict configuration. If you wish to use Polaris's public Sass API you
+// should explicitly import `_public-api.scss`
+// This file exists to maintain compatability with Sewing Kit < 0.113.0.
+// Any commits that modify this file's import list should also make the same
+// change in _public-api.scss
+// This file will be removed in Polaris v6.
 
 @import './shared/accessibility';
 @import './shared/breakpoints';

tests/build.test.ts

@@ -37,6 +37,7 @@ describe('build', () => {
     expect(fs.existsSync('./styles/global.scss')).toBe(true);
     expect(fs.existsSync('./styles/foundation.scss')).toBe(true);
     expect(fs.existsSync('./styles/shared.scss')).toBe(true);
+    expect(fs.existsSync('./styles/_public-api.scss')).toBe(true);
     expect(fs.existsSync('./styles/components.scss')).toBe(true);
   });