docs(overlays): add documentation on customization in scoped overlays (…

…ionic-team#21283)

- improves the documentation on customizing scoped overlays using cssClass and/or CSS variables
- includes a section in the Angular usage with information on where the CSS needs to be styled (globally) in order to work for an overlay

core/src/components/action-sheet/readme.md

@@ -6,6 +6,34 @@ An Action Sheet is a dialog that displays a set of options. It appears on top of
 
 A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role.
 
+### Customization
+
+Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector.
+
+We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the [Usage](#usage) section for an example of how to pass a class using `cssClass`.
+
+```css
+/* DOES NOT WORK - not specific enough */
+.action-sheet-group {
+  background: #e5e5e5;
+}
+
+/* Works - pass "my-custom-class" in cssClass to increase specificity */
+.my-custom-class .action-sheet-group {
+  background: #e5e5e5;
+}
+```
+
+Any of the defined [CSS Custom Properties](#css-custom-properties) can be used to style the Action Sheet without needing to target individual elements:
+
+```css
+.my-custom-class {
+  --background: #e5e5e5;
+}
+```
+
+> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
+
 
 <!-- Auto Generated Below -->
 
@@ -30,6 +58,7 @@ export class ActionSheetExample {
   async presentActionSheet() {
     const actionSheet = await this.actionSheetController.create({
       header: 'Albums',
+      cssClass: 'my-custom-class',
       buttons: [{
         text: 'Delete',
         role: 'destructive',
@@ -71,14 +100,19 @@ export class ActionSheetExample {
 ```
 
 
+### Style Placement
+
+In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Action Sheet can be presented from within a page, the `ion-action-sheet` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).
+
+
 ### Javascript
 
 ```javascript
 async function presentActionSheet() {
-
   const actionSheet = document.createElement('ion-action-sheet');
 
-  actionSheet.header = "Albums";
+  actionSheet.header = 'Albums';
+  actionSheet.cssClass = 'my-custom-class';
   actionSheet.buttons = [{
     text: 'Delete',
     role: 'destructive',
@@ -120,21 +154,23 @@ async function presentActionSheet() {
 
 ### React
 
-```typescript
+```tsx
 import React, { useState } from 'react';
 import { IonActionSheet, IonContent, IonButton } from '@ionic/react';
 import { trash, share, caretForwardCircle, heart, close } from 'ionicons/icons';
 
 export const ActionSheetExample: React.FC = () => {
-
   const [showActionSheet, setShowActionSheet] = useState(false);
 
   return (
     <IonContent>
-      <IonButton onClick={() => setShowActionSheet(true)} expand="block">Show Action Sheet</IonButton>
+      <IonButton onClick={() => setShowActionSheet(true)} expand="block">
+        Show Action Sheet
+      </IonButton>
       <IonActionSheet
         isOpen={showActionSheet}
         onDidDismiss={() => setShowActionSheet(false)}
+        cssClass='my-custom-class'
         buttons={[{
           text: 'Delete',
           role: 'destructive',
@@ -171,11 +207,8 @@ export const ActionSheetExample: React.FC = () => {
       >
       </IonActionSheet>
     </IonContent>
-
   );
-
 }
-
 ```
 
 
@@ -194,6 +227,7 @@ export class ActionSheetExample {
   async presentActionSheet() {
     const actionSheet = await actionSheetController.create({
       header: 'Albums',
+      cssClass: 'my-custom-class',
       buttons: [{
         text: 'Delete',
         role: 'destructive',
@@ -258,6 +292,7 @@ export default {
       return this.$ionic.actionSheetController
         .create({
           header: 'Albums',
+          cssClass: 'my-custom-class',
           buttons: [
             {
               text: 'Delete',

core/src/components/action-sheet/usage/angular.md

@@ -14,6 +14,7 @@ export class ActionSheetExample {
   async presentActionSheet() {
     const actionSheet = await this.actionSheetController.create({
       header: 'Albums',
+      cssClass: 'my-custom-class',
       buttons: [{
         text: 'Delete',
         role: 'destructive',
@@ -53,3 +54,8 @@ export class ActionSheetExample {
 
 }
 ```
+
+
+### Style Placement
+
+In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Action Sheet can be presented from within a page, the `ion-action-sheet` element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the `src/global.scss` file or you can register a new global style file by [adding to the `styles` build option in `angular.json`](https://angular.io/guide/workspace-config#style-script-config).

core/src/components/action-sheet/usage/javascript.md

@@ -1,9 +1,9 @@
 ```javascript
 async function presentActionSheet() {
-
   const actionSheet = document.createElement('ion-action-sheet');
 
-  actionSheet.header = "Albums";
+  actionSheet.header = 'Albums';
+  actionSheet.cssClass = 'my-custom-class';
   actionSheet.buttons = [{
     text: 'Delete',
     role: 'destructive',

core/src/components/action-sheet/usage/react.md

@@ -1,18 +1,20 @@
-```typescript
+```tsx
 import React, { useState } from 'react';
 import { IonActionSheet, IonContent, IonButton } from '@ionic/react';
 import { trash, share, caretForwardCircle, heart, close } from 'ionicons/icons';
 
 export const ActionSheetExample: React.FC = () => {
-
   const [showActionSheet, setShowActionSheet] = useState(false);
 
   return (
     <IonContent>
-      <IonButton onClick={() => setShowActionSheet(true)} expand="block">Show Action Sheet</IonButton>
+      <IonButton onClick={() => setShowActionSheet(true)} expand="block">
+        Show Action Sheet
+      </IonButton>
       <IonActionSheet
         isOpen={showActionSheet}
         onDidDismiss={() => setShowActionSheet(false)}
+        cssClass='my-custom-class'
         buttons={[{
           text: 'Delete',
           role: 'destructive',
@@ -49,9 +51,6 @@ export const ActionSheetExample: React.FC = () => {
       >
       </IonActionSheet>
     </IonContent>
-
   );
-
 }
-
 ```

core/src/components/action-sheet/usage/stencil.md

@@ -11,6 +11,7 @@ export class ActionSheetExample {
   async presentActionSheet() {
     const actionSheet = await actionSheetController.create({
       header: 'Albums',
+      cssClass: 'my-custom-class',
       buttons: [{
         text: 'Delete',
         role: 'destructive',

core/src/components/action-sheet/usage/vue.md

@@ -12,6 +12,7 @@ export default {
       return this.$ionic.actionSheetController
         .create({
           header: 'Albums',
+          cssClass: 'my-custom-class',
           buttons: [
             {
               text: 'Delete',