diff --git a/UNRELEASED.md b/UNRELEASED.md index 1f1dc720af4..d774366a470 100644 --- a/UNRELEASED.md +++ b/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)) diff --git a/config/rollup/plugins/styles.js b/config/rollup/plugins/styles.js index a38ee57873d..1650ba43fdc 100644 --- a/config/rollup/plugins/styles.js +++ b/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'; `; diff --git a/src/styles/_public-api.scss b/src/styles/_public-api.scss new file mode 100644 index 00000000000..6a52f980d7a --- /dev/null +++ b/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'; diff --git a/src/styles/foundation.scss b/src/styles/foundation.scss index 034f87a48d3..81c29fb5862 100644 --- a/src/styles/foundation.scss +++ b/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'; diff --git a/src/styles/shared.scss b/src/styles/shared.scss index 79b87be5659..7d48c5b4760 100644 --- a/src/styles/shared.scss +++ b/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'; diff --git a/tests/build.test.ts b/tests/build.test.ts index 4507dd27230..4350623493b 100644 --- a/tests/build.test.ts +++ b/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); });