From 5e1ef4b10fc5b4e866f9031e084b848ebd97022a Mon Sep 17 00:00:00 2001 From: Betti <167863867+bettiifr@users.noreply.github.com> Date: Wed, 25 Sep 2024 11:19:27 +0200 Subject: [PATCH 1/3] Edit doku --- .../documentation/docs/controls/charts/3d.md | 27 +++++--- .../docs/controls/charts/bar-chart.md | 20 +++++- .../docs/controls/charts/gauge-chart.md | 23 +++++-- .../docs/controls/charts/line-chart.md | 20 +++++- .../docs/controls/charts/overview.md | 66 +++++++++++++++++-- .../docs/controls/charts/pie-chart.md | 18 +++-- .../docs/controls/charts/special-chart.md | 11 +--- packages/form-field/form-field.md | 0 packages/validation/validation.md | 0 9 files changed, 146 insertions(+), 39 deletions(-) create mode 100644 packages/form-field/form-field.md create mode 100644 packages/validation/validation.md diff --git a/packages/documentation/docs/controls/charts/3d.md b/packages/documentation/docs/controls/charts/3d.md index 464694bb85f..4d033048023 100644 --- a/packages/documentation/docs/controls/charts/3d.md +++ b/packages/documentation/docs/controls/charts/3d.md @@ -3,6 +3,8 @@ import Playground from '@site/src/components/PlaygroundV3'; # 3D-Charting +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, enabling you to create immersive and interactive charts. With this package, you can design a variety of 3D charts, including: @@ -10,25 +12,32 @@ With this package, you can design a variety of 3D charts, including: - 3D bar charts - 3D surface plots + + + ## 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 in your project: + ```typescript import 'echarts-gl'; ``` -## Example - -### Basic +## Dos and Don'ts - - +- Do use appropriate data +- Do ensure that 3D charts are suitable for the presented data, they are most effective when additional dimensions are needed +- Don’t use 3D charts for simple data that can be effectively represented with 2D charts +- Don’t overuse 3D charts, they can make the data harder to interpret \ No newline at end of file diff --git a/packages/documentation/docs/controls/charts/bar-chart.md b/packages/documentation/docs/controls/charts/bar-chart.md index 4c1f7148ba5..3d9e2566b3e 100644 --- a/packages/documentation/docs/controls/charts/bar-chart.md +++ b/packages/documentation/docs/controls/charts/bar-chart.md @@ -3,9 +3,11 @@ import Playground from '@site/src/components/PlaygroundV3'; # Bar chart -## Examples +Bar charts are a type of chart that displays 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 + +The common bar chart is typically used to compare the values of different categories. The length of each bar is proportional to the value it represents. -### Bar chart horizontal stacked +### Stacked bar chart + +The stacked bar chart is 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. +## Dos and Don'ts + +- Do start the Y-axis at zero +- Do label axes clearly +- Do use short and clear category names +- Do include context only when necessary +- Do arrange categories and bars in logical order +- Don’t use too many bars in one chart +- Don’t overcrowd with colors and categories, especially within the stacked variant +- Don’t use stacked bars if the total value is not important diff --git a/packages/documentation/docs/controls/charts/gauge-chart.md b/packages/documentation/docs/controls/charts/gauge-chart.md index c481141b5a5..543154241df 100644 --- a/packages/documentation/docs/controls/charts/gauge-chart.md +++ b/packages/documentation/docs/controls/charts/gauge-chart.md @@ -3,9 +3,12 @@ import Playground from '@site/src/components/PlaygroundV3'; # Gauge chart -## 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 + +Metrics gauge chart, 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). -### Performance metrics gauge -### Progress circle gauge +### Circle gauge +Circle gauge chart, 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 circular shape 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. -### Progress arc gauge +### Arc gauge + +Arc gauge chart, also known as semi-circular progress bars, are a dynamic way to visualize data and track progress. Unlike circle charts, progress arc 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 space is limited, yet a clear and engaging visual representation is needed. + +## 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, yellow for caution, red for danger) to indicate different ranges +- Do label the ranges and the needle value clearly to avoid any confusion +- Don’t overcrowd the gauge with too many ranges or labels +- Don’t use gauge charts for complex data visualization or large datasets +- Don’t use similar colors for adjacent ranges to avoid confusion diff --git a/packages/documentation/docs/controls/charts/line-chart.md b/packages/documentation/docs/controls/charts/line-chart.md index ae54db4d75f..30edcb71762 100644 --- a/packages/documentation/docs/controls/charts/line-chart.md +++ b/packages/documentation/docs/controls/charts/line-chart.md @@ -3,11 +3,12 @@ import Playground from '@site/src/components/PlaygroundV3'; # Line chart - -## Examples +Line charts are a type of chart that displays data as a series of data points connected by straight line segments. Line charts are commonly used to visualize trends over time, or to show the comparison between two variables. We typically use line charts to visualize data that is continuous in nature. ### 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. + ### Multi-y-axis line chart +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 that has distinct patterns or trends. + ### Advanced line chart +Advanced line charts are an enhanced version of basic line charts, designed to provide deeper insights and 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. + + +## Dos and Don'ts + +- Do start the Y-axis at zero +- Do label axes clearly +- Do use contrasting colors for multiple lines to distinguish different data series better +- Do use consistent intervals on axes +- Do highlight important data points +- Do use visual cues to show gaps in data +- Don’t overcrowd with colors +- Don’t clutter the chart with too many lines (max. 7 lines) \ No newline at end of file diff --git a/packages/documentation/docs/controls/charts/overview.md b/packages/documentation/docs/controls/charts/overview.md index a08e39b850c..518ffbed7a2 100644 --- a/packages/documentation/docs/controls/charts/overview.md +++ b/packages/documentation/docs/controls/charts/overview.md @@ -6,21 +6,36 @@ 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 harness the power of ECharts with seamless integration into the Siemens Industrial Experience design system.
- 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) + +## Attributes + +| Name | Discription | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Axes** | Most charts have a horizontal (x-axis) and a vertical (y-axis) axis. These axes are labeled to indicate what data they represent. | +| **Scale** | Each axis has a scale, often marked with periodic graduations and numerical or categorical indications. | +| **Labels** | Axes labels describe the dimensions represented, often including units of measurement, e.g. “Distance traveled (m)”. | +| **Grid lines** | Grid lines help in visually aligning data points within the chart. | +| **Legend** | Legends explain the symbols, colors, or patterns used in the chart to represent different data sets. By clicking on the date in the legend, you can toggle the visibility of the data series. | +| **Tooltip** | Provides detailed information about data while hover over the area of interest. | + ## Installation +To install the Siemens Industrial Experience ECharts theme, run the 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 don't need to provide the `echarts` instance if it is 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'; @@ -28,11 +43,29 @@ import { registerTheme } from '@siemens/ix-echarts'; registerTheme(echarts); ``` -### Angular +
+For Angular make sure to correctly add `NgxEcharts` in your module file. +
+ +### 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) -Please make sure to correctly add `NgxEcharts` in your module file. +**Sequential data** +For ordered data, we recommend to use every second color (e.g. chart-1, chart-3, chart-5, ...). Example: monthly data. -## Examples +![Colors for sequential data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2412&t=MD9MvUCkoIcmSi8H-4) + +**Comparative data** +For comparing data within a category, we recommend to use the matching -40 color with 40% opacity. Example: last year and current year. + +![Colors for comparative data](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3225-2885&t=MD9MvUCkoIcmSi8H-4) + +### Loading indicator + +A loading indicator provides users with visual feedback that the chart is being processed and will be displayed shortly. This helps manage user expectations and enhances the overall user experience by preventing confusion or frustration during data loading times.  + +### Failure and error message + +A failure occurs when no data can be displayed within the chart. This can happen for various reasons, such as connection failure, missing data or other. Error messages have following three elements to move users forward: + +- State problem: What happened?​ Add a clear reason for the error, i.e. “No data available” +- Explain cause: Why did the error appear?​ A clear and concise message explaining why the error happened. "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” + +### Missing data points + +Indicate missing data with a special visual marker (like a different color or shape) to highlight the gaps without connecting them. diff --git a/packages/documentation/docs/controls/charts/pie-chart.md b/packages/documentation/docs/controls/charts/pie-chart.md index a452bc2499b..c513276059a 100644 --- a/packages/documentation/docs/controls/charts/pie-chart.md +++ b/packages/documentation/docs/controls/charts/pie-chart.md @@ -3,22 +3,30 @@ import Playground from '@site/src/components/PlaygroundV3'; # Pie chart -## Examples +Pie charts are a type of chart that displays 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. + +### Pie chart + +Pie charts are typically used to visualize the parts of a whole. Each slice represents a different category, with the size of the slice proportional to the value it represents. -### Donut chart -### Pie chart +### Donut chart + +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 an additional information can be displayed in the center of the chart. + + + diff --git a/packages/documentation/docs/controls/charts/special-chart.md b/packages/documentation/docs/controls/charts/special-chart.md index ac7a40857b5..8867d2b704d 100644 --- a/packages/documentation/docs/controls/charts/special-chart.md +++ b/packages/documentation/docs/controls/charts/special-chart.md @@ -6,18 +6,11 @@ import Playground from '@site/src/components/PlaygroundV3'; # Functionalities -ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases. - - -## Examples - +ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases. ### Interactive toolbox -Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. -By default, the toolbox appears in the top right corner of the chart. -You can customize this toolbox using the `toolbox` option within the option object. +Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. By default, the toolbox appears in the top right corner of the chart. The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience. You can customize this toolbox using the `toolbox` option within the option object. -The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience. Below is an example demonstrating some of the most commonly used tools and how to configure them to suit your needs. Date: Thu, 26 Sep 2024 12:20:42 +0200 Subject: [PATCH 2/3] Typo corrected --- packages/documentation/docs/controls/charts/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/docs/controls/charts/overview.md b/packages/documentation/docs/controls/charts/overview.md index 518ffbed7a2..ba5f8e5c35e 100644 --- a/packages/documentation/docs/controls/charts/overview.md +++ b/packages/documentation/docs/controls/charts/overview.md @@ -16,7 +16,7 @@ ECharts is a third party library distributed under [Apache License 2.0](https:// ## Attributes -| Name | Discription | +| Name | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Axes** | Most charts have a horizontal (x-axis) and a vertical (y-axis) axis. These axes are labeled to indicate what data they represent. | | **Scale** | Each axis has a scale, often marked with periodic graduations and numerical or categorical indications. | From 491825429ffde6bde3b9e0cafbba1936f3f6f4ad Mon Sep 17 00:00:00 2001 From: Betti <167863867+bettiifr@users.noreply.github.com> Date: Thu, 3 Oct 2024 12:58:00 +0200 Subject: [PATCH 3/3] Feedback integrated --- .../docs/controls/charts/overview.md | 34 +++++++++---------- .../docs/controls/charts/special-chart.md | 8 ++++- 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/packages/documentation/docs/controls/charts/overview.md b/packages/documentation/docs/controls/charts/overview.md index ba5f8e5c35e..d5ea9ff2300 100644 --- a/packages/documentation/docs/controls/charts/overview.md +++ b/packages/documentation/docs/controls/charts/overview.md @@ -16,15 +16,15 @@ ECharts is a third party library distributed under [Apache License 2.0](https:// ## Attributes -| Name | Description | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Axes** | Most charts have a horizontal (x-axis) and a vertical (y-axis) axis. These axes are labeled to indicate what data they represent. | -| **Scale** | Each axis has a scale, often marked with periodic graduations and numerical or categorical indications. | -| **Labels** | Axes labels describe the dimensions represented, often including units of measurement, e.g. “Distance traveled (m)”. | -| **Grid lines** | Grid lines help in visually aligning data points within the chart. | -| **Legend** | Legends explain the symbols, colors, or patterns used in the chart to represent different data sets. By clicking on the date in the legend, you can toggle the visibility of the data series. | -| **Tooltip** | Provides detailed information about data while hover over the area of interest. | - +| 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 in visually aligning 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 of interest. | +| | | ## Installation To install the Siemens Industrial Experience ECharts theme, run the follow the steps below: @@ -74,9 +74,13 @@ noMargin > -## Empty state +### Loading indicator + +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 yet ready. + +### Empty state -An empty state occurs when a user first opens an application, and no chart was added manually. Make sure to provide a clear message and a call to action to guide users on what to do next. +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.  -### Loading indicator - -A loading indicator provides users with visual feedback that the chart is being processed and will be displayed shortly. This helps manage user expectations and enhances the overall user experience by preventing confusion or frustration during data loading times.  - ### Failure and error message -A failure occurs when no data can be displayed within the chart. This can happen for various reasons, such as connection failure, missing data or other. Error messages have following three elements to move users forward: +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 following three elements to help users understand and resolve the issue: -- State problem: What happened?​ Add a clear reason for the error, i.e. “No data available” +- 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. "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” diff --git a/packages/documentation/docs/controls/charts/special-chart.md b/packages/documentation/docs/controls/charts/special-chart.md index 8867d2b704d..97738d30299 100644 --- a/packages/documentation/docs/controls/charts/special-chart.md +++ b/packages/documentation/docs/controls/charts/special-chart.md @@ -9,7 +9,13 @@ import Playground from '@site/src/components/PlaygroundV3'; ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases. ### Interactive toolbox -Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. By default, the toolbox appears in the top right corner of the chart. The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience. You can customize this toolbox using the `toolbox` option within the option object. +Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. By default, the toolbox appears in the top right corner of the chart. The toolbox includes various interactive tools, like +- download, +- zoom. +- zoom reset, +- restore, +each designed to enhance the user experience. +You can customize this toolbox using the `toolbox` option within the option object. Below is an example demonstrating some of the most commonly used tools and how to configure them to suit your needs.