Merge pull request #6016 from IgniteUI/apetrov/update-theme-docs

refactor(themes): updating docs
IgniteUI · Jan 28, 2025 · 3abaedb · 3abaedb
2 parents 63c8777 + b34ffe0
commit 3abaedb
Show file tree

Hide file tree

Showing 98 changed files with 2,673 additions and 5,289 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/en/.DS_Store b/en/.DS_Store
diff --git a/en/components/.DS_Store b/en/components/.DS_Store
diff --git a/en/components/accordion.md b/en/components/accordion.md
@@ -19,7 +19,7 @@ In it, you can see how to define an `igx-accrodion` and its [expansion panels]({
 
 <code-view style="height:460px" 
            data-demos-base-url="{environment:demosBaseUrl}" 
-           iframe-src="{environment:demosBaseUrl}/layouts/accordion-sample-1" alt="Angular Avatar Example">
+           iframe-src="{environment:demosBaseUrl}/layouts/accordion-sample-1" alt="Angular Accordion Example">
 </code-view>
 
 <div class="divider--half"></div>
@@ -239,7 +239,7 @@ You can see the result below.
 
 <code-view style="height:550px" 
            data-demos-base-url="{environment:demosBaseUrl}" 
-           iframe-src="{environment:demosBaseUrl}/layouts/accordion-sample-2" alt="Angular Avatar Example">
+           iframe-src="{environment:demosBaseUrl}/layouts/accordion-sample-2" alt="Angular Accordion Example">
 </code-view>
 
 <div class="divider--half"></div>
@@ -261,8 +261,9 @@ The [IgxAccordionComponent]({environment:angularApiUrl}/classes/igxaccordioncomp
  - <kbd>Home</kbd> - navigates to the FIRST enabled panel in the accordion
  - <kbd>End</kbd> - navigates to the LAST enabled panel in the accordion
 
-## Angular Accordion Styling
-The [accordion]({environment:angularApiUrl}/classes/igxaccordioncomponent.html) serves only as a container for the underlying [panels]({environment:angularApiUrl}/classes/igxexpansionpanelcomponent.html). Styles can be applied directly through the panel's theme, as described in the [styling section of the IgxExpansionPanel topic](expansion-panel.md#styling).
+## Styling
+
+The [`accordion`]({environment:angularApiUrl}/classes/igxaccordioncomponent.html) serves only as a container for the underlying [`panels`]({environment:angularApiUrl}/classes/igxexpansionpanelcomponent.html). Styles can be applied directly through the panel's theme, as described in the [`styling section of the IgxExpansionPanel topic`](expansion-panel.md#styling).
 
 By design, there is a margin set to the expanded panels, in case that they are positioned within an `igx-accordion`. In order to modify it there is a property exposed inside the igx-expansion-panel theme.
 In order to take advantage of the functions exposed by the theming engine, we have to import the `index` file in our style file:
@@ -274,33 +275,27 @@ In order to take advantage of the functions exposed by the theming engine, we ha
 // @import '~igniteui-angular/lib/core/styles/themes/index';
 ``` 
 
-Following the simplest approach, we create a new theme that extends the [expansion-panel-theme]({environment:sassApiUrl}/index.html#function-expansion-panel-theme) and accepts an `$expanded-margin` parameter. 
+Following the simplest approach, we create a new theme that extends the [`expansion-panel-theme`]({environment:sassApiUrl}/index.html#function-expansion-panel-theme) and accepts an `$expanded-margin`, `$body-color` and `$header-focus-background` parameters. 
 ```scss
 $custom-panel-theme: expansion-panel-theme(
-    $expanded-margin: 0px
+  $expanded-margin: 10px,
+  $body-color: #282885,
+  $header-focus-background: #efefef
 );
 ```
-### Using CSS Variables
 
 The last step is to include the component's theme.
 ```scss
-:host {
-    @include css-vars($custom-panel-theme);
-}
+@include css-vars($custom-panel-theme);
 ```
 
-### Using Theme Overrides
+### Demo
 
-In order to style components in Internet Explorer 11, we have to use a different approach, since CSS variables are not supported there.
+<code-view style="height:350px" 
+           data-demos-base-url="{environment:demosBaseUrl}" 
+           iframe-src="{environment:demosBaseUrl}/layouts/accordion-style" alt="Angular Accordion Style Example">
+</code-view>
 
-If the component is using the [Emulated](themes/sass/component-themes.md#view-encapsulation) `ViewEncapsulation`, it is necessary to `penetrate` this encapsulation using `::ng-deep`. To prevent the custom theme from leaking into other components, make sure to wrap the `::ng-deep` in a `:host` selector: 
-```scss
-:host {
-    ::ng-deep {
-        @include expansion-panel($custom-panel-theme);    
-    }
-}
-```
 ## API Reference
 * [IgxAccordion API]({environment:angularApiUrl}/classes/igxaccordioncomponent.html)
 * [IgxExpansionPanel API]({environment:angularApiUrl}/classes/igxexpansionpanelcomponent.html)

diff --git a/en/components/action-strip.md b/en/components/action-strip.md
@@ -5,21 +5,18 @@ _keywords: Angular Action Strip component, Angular Action Strip directive, Angul
 ---
 
 # Angular Action Strip Directive Overview
+
 <p class="highlight">
 The Ignite UI for Angular Action Strip component provides an overlay area containing one or more actions allowing additional UI and functionality to be shown on top of a specific target container upon user interaction e.g. hover. The container should be positioned relatively as the Action Strip attempts to overlay it and is itself positioned absolutely. Despite overlapped by an Action Strip, the main interactions and user access to the target container remain available.
 </p>
 
-<div class="divider--half"></div>
-
 ## Angular Action Strip Example
 
-
 <code-view style="height: 400px;" 
            data-demos-base-url="{environment:demosBaseUrl}" 
            iframe-src="{environment:demosBaseUrl}/menus/action-strip-paragraph" alt="Angular Action Strip Example">
 </code-view>
 
-
 <div class="divider--half"></div>
 
 ## Getting Started with Ignite UI for Angular Action Strip
@@ -32,7 +29,7 @@ ng add igniteui-angular
 
 For a complete introduction to the Ignite UI for Angular, read the [*getting started*](general/getting-started.md) topic.
 
-The next step is to import the `IgxActionStripModule` in your **app.module.ts** file. 
+The next step is to import the `IgxActionStripModule` in your **app.module.ts** file.
 
 ```typescript
 // app.module.ts
@@ -80,46 +77,46 @@ export class HomeComponent {}
 Now that you have the Ignite UI for Angular Action Strip module or directives imported, you can start with a basic configuration of the `igx-action-strip` component.
 
 ## Using the Angular Action Strip Component
+
 To initialize and position the Action Strip correctly, it needs to be inside a relatively positioned container:
 
 ```html
 <div style="position:relative; width:100px; height:100px;">
-    <igx-action-strip>
-        <button igxButton (click)="makeTextBold()">
-            <igx-icon>format_bold</igx-icon>
-        </button>
-    </igx-action-strip>
-<div>
+  <igx-action-strip>
+    <button igxButton (click)="makeTextBold()">
+      <igx-icon>format_bold</igx-icon>
+    </button>
+  </igx-action-strip>
+</div>
 ```
 
 By default, the Action Strip will be visible, but this can be configured via the [`hidden`]({environment:angularApiUrl}/classes/igxactionstripcomponent.html#hidden) @Input property.
 
 ### Menu look and feel
+
 For scenarios where more than three action items will be shown, it is best to use [`IgxActionStripMenuItem`]({environment:angularApiUrl}/classes/igxactionstripmenuitemdirective.html) directive. Any item within the Action Strip marked with the `*igxActionStripMenuItem` structural directive will be shown in a dropdown, revealed upon toggling the more button i.e. the three dots representing the last action.
 
 ```html
 <div style="position:relative; width:100px; height:100px;">
-    <igx-action-strip>
-        <button *igxActionStripMenuItem igxButton (click)="alignTextLeft()">
-            <igx-icon>format_align_left</igx-icon>
-        </button>
-        <button *igxActionStripMenuItem igxButton (click)="alignTextCenter()">
-            <igx-icon>format_align_center</igx-icon>
-        </button>
-        <button *igxActionStripMenuItem igxButton (click)="alignTextRight()">
-            <igx-icon>format_align_right</igx-icon>
-        </button>
-    </igx-action-strip>
+  <igx-action-strip>
+    <button *igxActionStripMenuItem igxButton (click)="alignTextLeft()">
+      <igx-icon>format_align_left</igx-icon>
+    </button>
+    <button *igxActionStripMenuItem igxButton (click)="alignTextCenter()">
+      <igx-icon>format_align_center</igx-icon>
+    </button>
+    <button *igxActionStripMenuItem igxButton (click)="alignTextRight()">
+      <igx-icon>format_align_right</igx-icon>
+    </button>
+  </igx-action-strip>
 </div>
 ```
 
-
 <code-view style="height: 400px;" 
            data-demos-base-url="{environment:demosBaseUrl}" 
            iframe-src="{environment:demosBaseUrl}/menus/action-strip-paragraph-menu" >
 </code-view>
 
-
 ### Reusing the Action Strip
 
 The same Action Strip instance can be used in multiple places in the document as long as the actions need not be visible simultaneously for them.
@@ -129,25 +126,25 @@ The best way to do so is via the [`show`]({environment:angularApiUrl}/classes/ig
 > [!NOTE]
 > The `show` API method uses [Angular Renderer2](https://angular.io/api/core/Renderer2) to append the Action Strip to that `element`.
 
-
 ## Usage in Grids
 
 The Action Strip provides additional functionality and UI for the IgxGrid.
 This can be utilized via grid action components and we are providing two default ones:
+
 - [`IgxGridEditingActionsComponent`]({environment:angularApiUrl}/classes/igxgrideditingactionscomponent.html) - includes functionality and UI related to grid editing. It allows you to quickly toggle edit mode for cells or rows, depending on the value of the `rowEditable` option of the grid and whether deleting rows is allowed.
 - [`IgxGridPinningActionsComponent`]({environment:angularApiUrl}/classes/igxgridpinningactionscomponent.html) - includes functionality and UI related to grid row pinning. It allows you to quickly pin rows and navigate between pinned rows and their disabled counterparts.
 
 ```html
 <igx-grid [data]="data" [rowEditable]="true" [primaryKey]="'ID'">
-    <igx-column *ngFor="let c of columns" [field]="c.field">
-    </igx-column>
+  <igx-column *ngFor="let c of columns" [field]="c.field"> </igx-column>
 
-    <igx-action-strip #actionStrip>
-        <igx-grid-pinning-actions></igx-grid-pinning-actions>
-        <igx-grid-editing-actions></igx-grid-editing-actions>
-    </igx-action-strip>
+  <igx-action-strip #actionStrip>
+    <igx-grid-pinning-actions></igx-grid-pinning-actions>
+    <igx-grid-editing-actions></igx-grid-editing-actions>
+  </igx-action-strip>
 </igx-grid>
 ```
+
 > [!NOTE]
 > These components inherit [`IgxGridActionsBaseDirective`]({environment:angularApiUrl}/classes/igxgridactionsbasedirective.html) and when creating a custom grid action component, it should also inherit `IgxGridActionsBaseDirective`.
 
@@ -165,52 +162,42 @@ This can be utilized via grid action components and we are providing two default
 ## Styling
 
 To customize the Action Strip, you first need to import the `index` file, where all styling functions and mixins are located.
+
 ```scss
 @use "igniteui-angular/theming" as *;
 
 // IMPORTANT: Prior to Ignite UI for Angular version 13 use:
 // @import '~igniteui-angular/lib/core/styles/themes/index';
-``` 
+```
+
 Next, we have to create a new theme that extends the `action-strip-theme` and pass the parameters which we'd like to change:
+
 ```scss
 $custom-strip: action-strip-theme(
-    $background: rgba(150, 133, 143, 0.4),
-    $actions-background: rgba(109, 121, 147, 0.6),
-    $icon-color: null,
-    $delete-action: null,
-    $actions-border-radius: 0
+  $background: rgba(150, 133, 143, 0.4),
+  $actions-background: rgba(109, 121, 147, 0.6),
+  $icon-color: null,
+  $delete-action: null,
+  $actions-border-radius: 0,
 );
 ```
 
 The last step is to include the newly created component theme in our application.
 
-When `$legacy-support` is set to `false`(default), include the component css variables like this:
 ```scss
 @include css-vars($custom-strip);
 ```
 
-When `$legacy-support` is set to `true`, include the component theme like this:
-```scss
-@include action-strip($custom-strip);
-```
-
 <code-view style="height: 400px;" 
            no-theming
            data-demos-base-url="{environment:demosBaseUrl}" 
            iframe-src="{environment:demosBaseUrl}/menus/action-strip-styling" >
 </code-view>
 
-## Known Issues and Limitations
-
-- Using the Action Strip component on IE11 requires the explicit import of the array polyfill in polyfill.ts of the angular application.
-
-    ```typescript
-    import 'core-js/es7/array';
-    ```
-
 ## API and Style References
 
 For more detailed information regarding the Action Strip API, refer to the following links:
+
 * [`IgxActionStripComponent API`]({environment:angularApiUrl}/classes/igxactionstripcomponent.html)
 
 The following built-in CSS styles helped us achieve this Action Strip layout:
@@ -224,10 +211,10 @@ Additional components and/or directives that can be used within the Action Strip
 * [`IgxGridEditingActionsComponent`]({environment:angularApiUrl}/classes/igxgrideditingactionscomponent.html)
 * [`IgxDividerDirective`]({environment:angularApiUrl}/classes/igxdividerdirective.html)
 
-
 <div class="divider"></div>
 
 ## Theming Dependencies
+
 * [IgxButton Theme]({environment:sassApiUrl}/index.html#function-button-theme)
 * [IgxRipple Theme]({environment:sassApiUrl}/index.html#function-ripple-theme)
 * [IgxDropDown Theme]({environment:sassApiUrl}/index.html#function-drop-down-theme)

diff --git a/en/components/autocomplete.md b/en/components/autocomplete.md
@@ -11,7 +11,6 @@ Angular Autocomplete is a search box directive that enables users to easily find
 
 The [`igxAutocomplete`]({environment:angularApiUrl}/classes/igxautocompletedirective.html) directive provides a way to enhance a text input by showing an [`igxDropDown`]({environment:angularApiUrl}/classes/igxdropdowncomponent.html) with suggested options, provided by the developer. The suggestions will show once you start typing in the text input or use the `Arrow Up`/`Arrow Down` keys.
 </p>
-<div class="divider"></div>
 
 ## Angular Autocomplete Example
 
@@ -256,7 +255,7 @@ The `drop-down` component, used as provider for suggestions, will expose the fol
 ## Styling
 Every component has its own theme.
 
-To get the `igxAutocomplete` styled, you have style its containing components. In our case, we need to use both the [input-group-theme]({environment:sassApiUrl}/index.html#function-input-group-theme) and the [drop-down-theme]({environment:sassApiUrl}/index.html#function-drop-down-theme).
+To get the `igxAutocomplete` styled, you have to style its containing components. In our case, these are the [input-group-theme]({environment:sassApiUrl}/index.html#function-input-group-theme) and the [drop-down-theme]({environment:sassApiUrl}/index.html#function-drop-down-theme).
 
 Take a look at the [`igxInputGroup`](input-group.md#styling) and the [`igxDropdown`](drop-down.md#styling) styling sections to get a better understanding of how to style those two components.
 

diff --git a/en/components/avatar.md b/en/components/avatar.md
@@ -92,8 +92,8 @@ We can also change the background through the `background` property or set a col
 // avatar.component.scss
 
 igx-avatar {
-    background: #e41c77;
-    color: #000000;
+  background: #e41c77;
+  color: #000000;
 }
 
 ```
@@ -155,45 +155,26 @@ Following the simplest approach, we create a new theme that extends the [`avatar
 Given the following markup:
 
 ```html
-<div class="initials-avatar">
-    <igx-avatar>BA</igx-avatar>
+<div class="avatar-sample initials">
+  <igx-avatar initials="JS" size="medium"></igx-avatar>
 </div>
 ```
 
-We need to create a theme:
+We create the following avatar theme:
 
 ```scss
 $custom-avatar-theme: avatar-theme(
-    $background: #72da67,
-    $color: #000000,
-    $border-radius: 16px
+  $background: #72da67,
+  $color: #000000,
+  $border-radius: 16px
 );
 ```
 
-### Using CSS variables 
-
 The last step is to pass the custom avatar theme:
 
 ```scss
-.initials-avatar {
-    @include css-vars($custom-avatar-theme);
-}
-```
-
-### Using mixins
-
-In order to style components for Internet Explorer 11 and older browsers, we have to use different approach, since it doesn't support CSS variables. 
-
-If the component is using an [`Emulated`](themes/sass/component-themes.md#view-encapsulation) ViewEncapsulation, it is necessary to `penetrate` this encapsulation using `::ng-deep`. On the other side, in order to prevent the custom theme to leak to other components, be sure to include the `:host` selector before `::ng-deep`:
-
-```scss
-:host {
-    ::ng-deep {
-        // Pass the custom avatar theme to the `igx-avatar` mixin
-        .initials-avatar {
-            @include avatar($custom-avatar-theme);
-        }
-    }
+.initials {
+  @include css-vars($custom-avatar-theme);
 }
 ```
 
@@ -233,7 +214,7 @@ You can also use one of the predefined sizes, assigning it to the `--ig-size` va
 
 ```scss
 igx-avatar {
-    --ig-size: var(--ig-size-small);
+  --ig-size: var(--ig-size-small);
 }
 ```