Merge remote-tracking branch 'origin/main' into release-3.0.0

packages/angular-test-app/src/app/app-routing.module.ts

@@ -21,6 +21,7 @@ import Avatar from '../preview-examples/avatar';
 import AvatarImage from '../preview-examples/avatar-image';
 import AvatarInitials from '../preview-examples/avatar-initials';
 import BasicNavigation from '../preview-examples/basic-navigation';
+import BasicNavigationMigration from '../preview-examples/basic-navigation-migration';
 import BasicNavigationWithoutHeader from '../preview-examples/basic-navigation-without-header';
 import Blind from '../preview-examples/blind';
 import BlindHeaderActions from '../preview-examples/blind-header-actions';
@@ -146,6 +147,7 @@ import LinkButton from '../preview-examples/link-button';
 import LinkButtonDisabled from '../preview-examples/link-button-disabled';
 import Loading from '../preview-examples/loading';
 import MapNavigation from '../preview-examples/map-navigation';
+import MapNavigationMigration from '../preview-examples/map-navigation-migration';
 import MapNavigationOverlay from '../preview-examples/map-navigation-overlay';
 import MenuCategory from '../preview-examples/menu-category';
 import MenuWithBottomTabs from '../preview-examples/menu-with-bottom-tabs';
@@ -227,8 +229,6 @@ import VerticalTabs from '../preview-examples/vertical-tabs';
 import VerticalTabsWithAvatar from '../preview-examples/vertical-tabs-with-avatar';
 import Workflow from '../preview-examples/workflow';
 import WorkflowVertical from '../preview-examples/workflow-vertical';
-import MapNavigationMigration from '../preview-examples/map-navigation-migration';
-import BasicNavigationMigration from '../preview-examples/basic-navigation-migration';
 
 const routes: Routes = [
   {

packages/angular-test-app/src/app/app.module.ts

@@ -156,6 +156,7 @@ import LinkButton from '../preview-examples/link-button';
 import LinkButtonDisabled from '../preview-examples/link-button-disabled';
 import Loading from '../preview-examples/loading';
 import MapNavigation from '../preview-examples/map-navigation';
+import MapNavigationMigration from '../preview-examples/map-navigation-migration';
 import MapNavigationOverlay from '../preview-examples/map-navigation-overlay';
 import MenuCategory from '../preview-examples/menu-category';
 import MenuWithBottomTabs from '../preview-examples/menu-with-bottom-tabs';
@@ -237,7 +238,6 @@ import VerticalTabs from '../preview-examples/vertical-tabs';
 import VerticalTabsWithAvatar from '../preview-examples/vertical-tabs-with-avatar';
 import Workflow from '../preview-examples/workflow';
 import WorkflowVertical from '../preview-examples/workflow-vertical';
-import MapNavigationMigration from '../preview-examples/map-navigation-migration';
 
 @NgModule({
   declarations: [

packages/documentation/docs/controls/charts/3d.md

@@ -1,33 +1,40 @@
 import Playground from '@site/src/components/PlaygroundV3';
 
-# 3D-Charting
+# 3D charts
 
-The `echarts-gl` package extends ECharts to support 3D visualizations, enabling you to create immersive and interactive charts.
-With this package, you can design a variety of 3D charts, including:
+3D charts are a powerful way to visualize data in three dimensions. They provide a more immersive and interactive experience compared to traditional 2D charts. We typically use 3D charts to represent complex data sets or to visualize data in a more engaging way.
+
+The `echarts-gl` package extends ECharts to support 3D visualizations. With this package, you can design a variety of 3D charts, including:
 
 - 3D scatter plots
 - 3D bar charts
 - 3D surface plots
 
+<Playground
+height="40rem"
+name="echarts-special-3d"
+noMargin
+examplesByName>
+</Playground>
+
 ## Installation
 
+To install the `echarts-gl` package, run the following command:
+
 ```sh
 npm install --save @siemens/ix-echarts
 ```
 
 ## Import
 
+To use 3D charts, import the `echarts-gl` package into your project:
+
 ```typescript
 import 'echarts-gl';
 ```
 
-## Example
-
-### Basic
+## Dos and Don'ts
 
-<Playground
-height="40rem"
-name="echarts-special-3d"
-noMargin
-examplesByName>
-</Playground>
+- Do use with data that's best seen and interpreted in  multiple dimensions
+- Don’t use 3D charts for simple data that can be effectively represented with 2D charts
+- Don’t overuse 3D charts as they can make the data harder to interpret

packages/documentation/docs/controls/charts/bar-chart.md

@@ -1,10 +1,12 @@
 import Playground from '@site/src/components/PlaygroundV3';
 
-# Bar chart
+# Bar charts
 
-## Examples
+Bar charts display data using rectangular bars. The length of each bar is proportional to the value it represents. Bar charts are commonly used to compare the values of different categories. We typically use bar charts to visualize data that is categorical or ordinal in nature.
 
-### Bar chart horizontal
+### Bar chart
+
+Common bar charts normally compare the values of different categories where the length of the bars are proportional to their values.
 
 <Playground
 height="40rem"
@@ -13,7 +15,9 @@ noMargin
 examplesByName>
 </Playground>
 
-### Bar chart horizontal stacked
+### Stacked bar chart
+
+Stacked bar charts are typically used to visualize the relationship between the parts and the whole. Each bar is divided into segments, with each segment representing a different category.
 
 <Playground
 height="40rem"
@@ -22,5 +26,14 @@ noMargin
 examplesByName>
 </Playground>
 
+## Dos and Don'ts
+
+- Do start the Y-axis at zero and label axes clearly
+- Do use short and clear category names
+- Do include context and additional information when necessary
+- Do arrange categories and bars in a logical order
+- Don’t use too many bars in one chart
+- Don’t overcrowd charts with colors and categories, especially the stacked variant
+- Don’t use stacked bars if the total value is not important
 
 

packages/documentation/docs/controls/charts/gauge-chart.md

@@ -1,10 +1,13 @@
 import Playground from '@site/src/components/PlaygroundV3';
 
-# Gauge chart
+# Gauge charts
 
-## Examples
+Gauge charts are a type of chart that displays data using a dial or needle to indicate a value within a specific range. Gauge charts are commonly used to visualize performance metrics, such as speedometers, progress meters, and other KPIs. We typically use gauge charts to represent a single value within a range of values.
+
+### Metric gauge charts
+
+Metrics gauge charts, also known as dial or speedometer charts, are an effective way to visualize key performance indicators (KPIs) and other metrics. These charts indicate the current value of a metric within a predefined range, often segmented into different zones, e.g. red for poor performance, green for good performance, etc. 
 
-### Performance metrics gauge
 
 <Playground
 height="25rem"
@@ -13,7 +16,9 @@ noMargin
 examplesByName>
 </Playground>
 
-### Progress circle gauge
+### Circle gauge charts
+
+Circle gauge charts, also known as radial progress charts or circular progress bars, are a visually appealing way to represent data and track progress towards a goal. These charts use a circle to display the percentage of completion, making it easy to quickly grasp the status of a project or task. The circle is typically filled in proportion to the progress made, with the center often displaying the percentage value.
 
 <Playground
 height="30rem"
@@ -22,11 +27,22 @@ noMargin
 examplesByName>
 </Playground>
 
-### Progress arc gauge
+### Arc gauge charts
+
+Arc gauge charts, also known as semi-circular progress bars, are a dynamic way to visualize data and track progress. Unlike circle charts, arc gauge charts use a semi-circle or arc to represent the percentage of completion. This design can be particularly effective in dashboards and user interfaces where users need a clear and engaging visual representation but space is limited.
 
 <Playground
 height="30rem"
 name="echarts-progress-arc"
 noMargin
 examplesByName>
 </Playground>
+
+## Dos and Don'ts
+
+- Do keep it simple and easy to read, with a clear needle and well-defined ranges
+- Do use color coding, e.g. green for good, red for danger, etc. to indicate different ranges
+- Do label ranges and the needle value clearly to avoid  confusion
+- Don’t overcrowd the gauge with too many ranges or labels
+- Don’t use gauge charts for visualizing complex data or large datasets
+- Don’t use similar colors for adjacent ranges to avoid confusion

packages/documentation/docs/controls/charts/line-chart.md

@@ -1,11 +1,12 @@
 import Playground from '@site/src/components/PlaygroundV3';
 
-# Line chart
+# Line charts
 
+Line charts display data as a series of data points connected by straight line segments. Line charts are commonly used to visualize trends over time or compare two variables. We typically use line charts to visualize continuous data.
 
-## Examples
+### Basic line charts
 
-### Basic line chart
+Basic line charts use a series of data points connected by straight lines to show changes in values, making it easy to identify patterns, trends and fluctuations. Line charts are particularly effective for displaying continuous data, such as stock prices, temperature changes or sales figures. Their simplicity and clarity make them a popular choice for dashboards, where understanding data trends is essential.
 
 <Playground
 height="40rem"
@@ -14,7 +15,9 @@ noMargin
 examplesByName>
 </Playground>
 
-### Multi-y-axis line chart
+### Multi-y-axis line charts
+
+Multi-y-axis line charts are used to compare multiple data series that have different scales or units of measurement. By using multiple y-axes, you can display data with different ranges on the same chart, making it easier to compare trends and relationships between variables. Multi-y-axis line charts are particularly useful when visualizing data with distinct patterns or trends.
 
 <Playground
 height="40rem"
@@ -23,11 +26,23 @@ noMargin
 examplesByName>
 </Playground>
 
-### Advanced line chart
+### Advanced line charts
+
+Advanced line charts are an enhanced version of basic line charts, designed to provide deeper insights and a more detailed analysis of data trends. These charts often incorporate features such as multiple data series, interactive elements, and additional annotations to highlight key points or events. Advanced line charts can also include trend lines, moving averages and other statistical tools to help identify patterns and correlations.
 
 <Playground
 height="40rem"
 name="echarts-line-advanced"
 noMargin
 examplesByName>
 </Playground>
+
+## Dos and Don'ts
+
+- Do start the Y-axis at zero and label axes clearly
+- Do use contrasting colors for multiple lines to better distinguish different data series 
+- Do use consistent intervals on axes
+- Do highlight important data points
+- Do use visual cues to show gaps in data
+- Don’t overcrowd the chart with colors
+- Don’t clutter the chart with too many lines, we recommend no more than 7 lines

packages/documentation/docs/controls/charts/overview.md

@@ -6,44 +6,98 @@ import Playground from '@site/src/components/PlaygroundV3';
 # Basics
 
 Siemens Industrial Experience provides a theme for the popular chart library [ECharts](https://echarts.apache.org/handbook/en/get-started).
-This lets you harness the power of ECharts with seamless integration into the Siemens Industrial Experience styleguide.
+This lets you seamlessly integrate ECharts into the Siemens Industrial Experience design system.
 
 <div className="siemens-brand-section">
+ECharts is a third-party library distributed under [Apache License 2.0](https://www.apache.org/licenses).
+</div>
 
-ECharts is a third party library distributed under [Apache License 2.0](https://www.apache.org/licenses).
+![Chart usage guide](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3532-4181&t=MD9MvUCkoIcmSi8H-4)
 
-</div>
+## Attributes
 
+| Name           | Description                                                                                                                                                                                  |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Axes**       | Axes are used to display the data in a chart. They are the horizontal and vertical lines that form the chart's grid. Axes are labeled to indicate what data they represent.                  |
+| **Scale**      | Scales are used to map data values to a visual representation. The scale type is determined by the type of data being visualized.                                                            |
+| **Labels**     | Labels are used to describe the dimensions represented, often including units of measurement, e.g. “Distance traveled (m)”.                                                                  |
+| **Grid lines** | Grid lines help to visually align data points within the chart.                                                                                                                           |
+| **Legend**     | Legends explain the symbols, colors or patterns used in the chart to represent different data sets. You can toggle the visibility of the data series by clicking on the date in the legend. |
+| **Tooltip**    | Tooltips provide more details about data while hovering over the area.                                                                                                           |
+|                |                                                                                                                                                                                              |
 ## Installation
 
+To install the Siemens Industrial Experience ECharts theme, follow the steps below:
+
 ```sh
 npm install --save @siemens/ix-echarts
 ```
 
-First, import the `registerTheme` function from our module. Then, invoke this function, passing in your `echarts` instance as an argument. You don't need to provide the `echarts` instance if it is provided globally in your `window` object when using vanilla Javascript. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark`, and `classic-light` themes for your chart.
+1. Import the `registerTheme` function from our module. 
+2. Invoke this function, passing in your `echarts` instance as an argument. You do not need to provide the `echarts` instance if it's provided globally in your `window` object when using vanilla Javascript. 
+3. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark` and `classic-light` themes for your chart.
 
 ```typescript
 import { registerTheme } from '@siemens/ix-echarts';
 
 registerTheme(echarts);
 ```
 
-### Angular
+<div className="Angular">
+For Angular, make sure to correctly add `NgxEcharts` in your module file.
+</div>
+
+### Colors
+
+The Siemens Industrial Experience ECharts theme provides a set of colors that are used to style the charts. These colors are optimized for accessibility and readability. 
+
+**Categorical data**
+For easily distinguishable data series where each category is distinct but not ordered, we recommend the following color sequence. 
+Example: Different product types or regions.
+
+![Colors for categorical data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3223-1647&t=MD9MvUCkoIcmSi8H-4)
+
+**Sequential data**
+For ordered data, we recommend using every second color, e.g. chart-1, chart-3, chart-5, etc. Example: monthly data.
+
+![Colors for sequential data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2412&t=MD9MvUCkoIcmSi8H-4)
 
-Please make sure to correctly add `NgxEcharts` in your module file.
+**Comparative data**
+For comparing data within a category, we recommend using the matching -40 color with 40% opacity. Example: last year and current year.
 
-## Examples
+![Colors for comparative data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2885&t=MD9MvUCkoIcmSi8H-4)
 
 <Playground
 height="40rem"
 name="echarts"
 noMargin>
 </Playground>
 
-## Empty state
+### Loading indicators
+
+A loading indicator provides users with visual feedback that the chart is being processed and will be displayed shortly. The loading indicator should be displayed when the chart is loading data or rendering, to visually indicate that the chart is not ready yet. 
+
+### Empty states
+
+An empty state occurs when a user first opens an application, no data is available, or the user has filtered out all data. The empty state should be visually distinct from the loading state and should provide a clear message to the user. This message should explain why the empty state is being displayed and provide guidance on how to proceed. 
 
 <Playground
 height="40rem"
 name="echarts-empty-state"
 noMargin>
 </Playground>
+
+### Failure and error messages
+
+A failure occurs when no data can be displayed within the chart. This can happen for various reasons, such as connection failure and missing data. Error messages have the following elements to help users understand and resolve any issues:
+
+- State problem: What happened?​ Add a clear reason for the error, e.g. “No data available”
+- Explain cause: Why did the error appear?​ A clear and concise message explaining why the error happened, e.g. "Connection failure"
+- Give solution: What can the user do to proceed?​  
+    Add clear instructions for the user regarding what to do next to resolve the error, e.g. “Try again”
+
+For more detailed information and examples, see the UX writing style guide. 
+
+### Missing data points
+
+Indicate missing data with a special visual marker (like a different color or shape) to highlight the gaps without connecting them.

packages/documentation/docs/controls/charts/pie-chart.md

@@ -1,23 +1,26 @@
 import Playground from '@site/src/components/PlaygroundV3';
 
-# Pie chart
+# Pie charts
 
-## Examples
+Pie charts display data using a circular graph. The length of each slice is proportional to the value it represents. Pie charts are commonly used to visualize the parts of a whole and are particularly useful for comparing the relative sizes of different categories.
 
-### Donut chart
+### Pie chart example
 
 <Playground
 height="40rem"
-name="echarts-circle"
+name="echarts-pie"
 noMargin
 examplesByName>
 </Playground>
 
-### Pie chart
+### Donut charts
+
+Donut charts are a variation of pie charts that have a hole in the center. Donut charts are often used to display the same information as a pie chart, but additional information can be displayed in the center of the chart.
 
 <Playground
 height="40rem"
-name="echarts-pie"
+name="echarts-circle"
 noMargin
 examplesByName>
 </Playground>
+