docs: extend PurgeCSS integration documentation (#1313)

* fix "check sentence newline" script to accept "i.e." and "e.g." as being not sentence ends

docs/check-sentence-newline.js

@@ -15,7 +15,7 @@ files.forEach(file => {
       if (/^(>|#|\||\s*-|\s*[0-9]+\.)/.test(line)) {
         return line;
       } else {
-        return line.replace(/((?!i\.e)\.) ([A-Z0-9])/g, '$1\n$2');
+        return line.replace(/((?<!i\.e|e\.g)\.) ([A-Z0-9])/g, '$1\n$2');
       }
     })
     .join('\n');

docs/concepts/styling-behavior.md

@@ -51,6 +51,11 @@ To integrate an icon
 
 If an icon is not available yet, you need to add it to `src\app\core\icon.module.ts` in the `import {}` and the `constructor(){}`.
 
+## Optimization
+
+The PWA uses [PurgeCSS](https://purgecss.com/) for bundled styles optimization.
+Please read [the additional documentation](../guides/optimizations.md#purgecss) for information on the usage and configuration of PurgeCSS in the Intershop PWA.
+
 ## References
 
 [Guide - Multiple Themes](../guides/multiple-themes.md)

docs/guides/customizations.md

@@ -81,7 +81,7 @@ Typical hot-spots where copying is a good idea are header-related or product-det
 #### Theme Specific Overrides
 
 The [customized webpack build](./optimizations.md) supports replacing any file with an environment suffix in front of the file extension.
-If you for example want to customize the template `product-detail.component.html`, put your customized content in the parallel file `product-detail.component.brand.html` and run a build with `--configuration=brand`.
+If you for example want to customize the template `product-detail.component.html`, put your customized content in the parallel file `product-detail.component.theme.html` and run a build with `--configuration=theme`.
 Then this overridden component template will be swapped in.
 
 This also works for multiple configurations: `product-detail.component.foo.bar.baz.html` will be active for configurations `foo`, `bar` and `baz`, but not for `foobar`.
@@ -155,7 +155,7 @@ There are two approaches to apply a theme specific styling:
 1. Copy only the `*.scss` files you need to change to your themes folder and adjust the file references. All files which are not overwritten in your theme will be taken from the standard and all changes and bugfixes in these files when migrating the PWA will be applied and used in your project.
 2. Copy the complete set of standard `*.scss` files to your themes folder and adjust the file references. All standard changes and bugfixes to `*.scss` files will not be applied to your theme during a PWA migration.
 
-Just putting a brand override file next to the original file in the `src/styles` folder will not lead to the expected results.
+Just putting a theme override file next to the original file in the `src/styles` folder will not lead to the expected results.
 The lookup starts with the file `style.scss` in the theme specific folder.
 
 > **Note:** You should
@@ -164,6 +164,7 @@ The lookup starts with the file `style.scss` in the theme specific folder.
 > - not delete the standard theme folders to prevent merge conflicts when migrating the PWA (changes in standard files but deleted in your project).
 
 When styling is done on component level, all styling is encapsulated to exactly this component (default behavior).
+On component level, theme-specific overrides for `.scss` files work as expected.
 
 You can re-use variables from the global styling on component level by importing only the styling file that defines the theme variables, e.g.
 
@@ -173,10 +174,14 @@ You can re-use variables from the global styling on component level by importing
 
 > **Note:** Be aware that Visual Studio Code will not resolve all import references correctly but it works in the build PWA version anyways.
 
+> **Note:** For bundled styles optimization PurgeCSS is used. Please read [the additional documentation](./optimizations.md#purgecss) regarding the usage and configuration of PurgeCSS in the Intershop PWA.
+
+### Static Assets
+
 To add static assets (images, favicon, manifest file), create a theme specific folder in `src/assets/themes/<theme-prefix>` and adjust the theme specific references in the `*.scss` files accordingly.
 
-The `index.html` does not support the theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides).
-Therefore, any theme specific references have to be changed directly in this file.
+The `index.html` does not support theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides).
+For this file, any theme specific differences are handled via [theme.service.ts](../../src/app/core/utils/theme/theme.service.ts).
 
 ### Dependencies
 

docs/guides/optimizations.md

@@ -27,7 +27,43 @@ If the PWA is built using `production` configuration. (Either by building with `
 - Webpack [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/) is instructed to produce only `main`, `vendor`, `polyfills` and one `common` bundle for the code for optimized compression and download of the application.
 - All `data-testing` attributes are removed from the HTML templates to reduce output.
 - [PurgeCSS](https://purgecss.com) is used to remove unused CSS classes from the CSS output.
-  [Configuration](https://purgecss.com/configuration.html), especially [safelisting](https://purgecss.com/safelisting.html) certain classes, can be done on the plugin configuration or directly in your CSS with a special comment.
+
+## PurgeCSS
+
+> PurgeCSS is a tool to remove unused CSS. It can be part of your development workflow. When you are building a website, you might decide to use a CSS framework like TailwindCSS, Bootstrap, MaterializeCSS, Foundation, etc... But you will only use a small set of the framework, and a lot of unused CSS styles will be included.
+
+> This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your CSS files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files.
+
+While the described function for deleting unused CSS styles is very helpful, the mechanism for determining which styles are used is not without problems.
+PurgeCSS can only analyze the strings in the actual source code of the project for used styles.
+
+So, styles that get added to the rendered HTML by third-party libraries (e.g. Bootstrap, Swiper) would not be found.
+The same applies for styles used in server-loaded content (e.g. CMS, product descriptions).
+Also style selectors that are dynamically generated would not be found.
+
+### Safelisting
+
+To solve this problem PurgeCSS provides different [options for safelisting](https://purgecss.com/safelisting.html) specific styles.
+This can either be done in the plugin configuration or directly in your SCSS/CSS files with special comments.
+
+The PurgeCSS plugin configuration can be found in the project's [`webpack.custom.ts`](https://github.com/intershop/intershop-pwa/blob/3.1.0/templates/webpack/webpack.custom.ts#L231-L246).
+This method is used and recommended to include required styles of the third-party libraries used, which would otherwise be purged.
+For the different [configuration options](https://purgecss.com/configuration.html), refer to the PurgeCSS documentation.
+
+To protect styles defined in the Intershop PWA project source code, Intershop recommends safelisting them directly in your SCSS/CSS with [special comments](https://purgecss.com/safelisting.html#in-the-css-directly).
+To include nested SCSS definitions, use `/* purgecss start ignore */` and `/* purgecss end ignore */`.
+
+### Development
+
+When using the standard way of developing the PWA with `ng s`, PurgeCSS is not activated and styling should work as expected.
+This way missing styling issues because of PurgeCSS often first show up in deployed environments.
+To test or develop with enabled PurgeCSS, the development server needs to be started with `ng s -c=b2b,production` (or your desired theme instead of `b2b`).
+
+In this startup process the following line can be read, indicating the usage of PurgeCSS similar to the deployed builds:
+
+```
+serve@b2b,production: setting up purgecss CSS minification
+```
 
 # Further References