diff --git a/change/@fluentui-react-charting-8c7e2a0d-fb53-4e19-9c69-3cddec6c7b24.json b/change/@fluentui-react-charting-8c7e2a0d-fb53-4e19-9c69-3cddec6c7b24.json new file mode 100644 index 0000000000000..78154da06da38 --- /dev/null +++ b/change/@fluentui-react-charting-8c7e2a0d-fb53-4e19-9c69-3cddec6c7b24.json @@ -0,0 +1,7 @@ +{ + "type": "patch", + "comment": "Updating documentation content", + "packageName": "@fluentui/react-charting", + "email": "atishay.jain@microsoft.com", + "dependentChangeType": "patch" +} diff --git a/packages/react-charting/README.md b/packages/react-charting/README.md index c8f189f9be821..a08ae8952a68a 100644 --- a/packages/react-charting/README.md +++ b/packages/react-charting/README.md @@ -67,7 +67,7 @@ The library has a wide variety of tests to ensure quality of the library. The tests range from component tests, unit tests, visual regression tests, accessibility tests, integration tests and manual tests. The test automations aim to ensure over 90% code coverage across the library. -Further details available in the wiki +Further details available in the [wiki](https://aka.ms/fluentChartingWiki) Run `yarn test` from within the package to run all the tests. @@ -75,25 +75,67 @@ Run `yarn test` from within the package to run all the tests. Our charts have elaborate accessibility support. The charts are WCAG 2.1 MAS C compliant for accessibility. -More details are covered in the wiki. +More details are covered in the [wiki](https://aka.ms/fluentChartingWiki). ## Performance Performance is a key success criteria for the charting library. Performance is measured and has been improved for the following scenarios. -|**S No**| **Scenario** | **Lighthouse Score** | -|:------:|:------------------------------------------------: | :----------------------: | -| 1. | 1 LineChart of 1 series with 30,000 datapoints | 79.2 | -| 2. | 6 LineCharts of 1 series with 100 datapoints each | 98.8 | -| 3. | 18 LineCharts of 1 series with 5 datapoints | 98 | -| 4. | 50 Linecharts of 1 Series with 10 datapoints each | 89.6 | -| 5. | 1 Linechart of 2 series with 500 datapoints each | 98.6 | -| 6. |10 Linecharts of 1 series with 1000 datapoints each| 94.4 | -| 7. | 1 Areachart with 30,000 datapoints | 49 | -| 8. | 6 Areacharts of 1 series with 100 datapoints each | 95.4 | -| 9. |18 Areacharts of 1 series with 5 data points each | 96.8 | - -More details are covered in the wiki. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
S NoScenarioLighthouse Score
1.1 LineChart of 1 series with 30,000 datapoints79.2
2.6 LineCharts of 1 series with 100 datapoints each98.8
3.18 LineCharts of 1 series with 5 datapoints98
4.50 Linecharts of 1 Series with 10 datapoints each89.6
5.1 Linechart of 2 series with 500 datapoints each98.6
6.10 Linecharts of 1 series with 1000 datapoints each94.4
7.1 Areachart with 30,000 datapoints49
8.6 Areacharts of 1 series with 100 datapoints each95.4
9.18 Areacharts of 1 series with 5 data points each96.8
+ +More details are covered in the [wiki](https://aka.ms/fluentChartingWiki). ## Versioning and changelog diff --git a/packages/react-examples/src/react-charting/AreaChart/AreaChart.doc.tsx b/packages/react-examples/src/react-charting/AreaChart/AreaChart.doc.tsx index 939ab29af2543..08b8c180d72b6 100644 --- a/packages/react-examples/src/react-charting/AreaChart/AreaChart.doc.tsx +++ b/packages/react-examples/src/react-charting/AreaChart/AreaChart.doc.tsx @@ -52,6 +52,8 @@ export const AreaChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/AreaChart/AreaChartPage.tsx b/packages/react-examples/src/react-charting/AreaChart/AreaChartPage.tsx index feec01b865e2b..cf44d5647addb 100644 --- a/packages/react-examples/src/react-charting/AreaChart/AreaChartPage.tsx +++ b/packages/react-examples/src/react-charting/AreaChart/AreaChartPage.tsx @@ -75,6 +75,16 @@ export class AreaChart extends React.Component { {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md index ee640b1ce0f1d..d12a10cd37b84 100644 --- a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md +++ b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md @@ -1,3 +1,36 @@ +### Layout + +Padding on the left and right of the chart is determined by the x-axis labels - it should start and end at or close to the first and last tick mark. The minimum padding is 8px. + +Currently we support stacked area charts only. + ### Content -AreaChart best practices content placeholder. +- **Area line** An area line represents a set of values from the same data set. Each line takes on a new swatch in the data visualization library to distinguish it from others. 2px wide. There is no rounding of joints to avoid data misrepresentation. +- **Area fill** Uses the same color family as the area line, but applies a 50% opacity. + +**Note:** the implemented stacked area components use transparency fills, but we cannot apply transparency in the Figma guidance + +### Accessibility + +- Users "Enter" into the graph and can use both arrow and tab keys to navigate through. +- The first tab stop will stop on the graph and give a description of what type of graph it is. +- Each section of the graph is readable via screen readers. The user can navigate through the entire area plot by using Left and Right arrow keys. + +### Interaction + +The area chart is a highly performant visual. It uses a path-based rendering mechanism to render the area component. On hovering, the nearest x datapoint is identified and the corresponding point is hovered. + +### Customizing the chart + +- **Stacked area chart** + In stacked area chart, two or more data series are stacked vertically. It helps in easy comparison across different dimensions. The callout on hover for stacked chart displays multiple values from the stack. The callout can be customized to show single values or stacked values. Refer to the props `onRenderCalloutPerDataPoint` and `onRenderCalloutPerStack` using which custom content for the callout can be defined. +- **Custom accessibility** + Area chart provides a bunch of props to enable custom accessibility messages. Use `xAxisCalloutAccessibilityData` and `callOutAccessibilityData` to configure x axis and y axis accessibility messages, respectively. + +#### Axis localization + +The chart axes support 2 ways of localization. + +1. JavaScript provided inbuilt localization for numeric and date axis. Specify the culture and `dateLocalizeOptions` for date axis to define target localization. Refer the [Javascript localization guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString) for usage. +2. Custom locale definition: The consumer of the library can specify a custom locale definition as supported by d3 [like this](https://github.com/d3/d3-time-format/blob/main/locale/en-US.json). The date axis will use the date range and the multiformat specified in the definition to determine the correct labels to show in the ticks. For example - If the date range is in days, then the axis will show hourly ticks. If the date range spans across months, then the axis will show months in tick labels and so on. Specify the custom locale definition in the `timeFormatLocale` prop. Refer to the Custom Locale Date Axis example in line chart for sample usage. diff --git a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md new file mode 100644 index 0000000000000..0e9f6e97ce12f --- /dev/null +++ b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md @@ -0,0 +1,3 @@ +- Prefer line charts to plot trends. +- No more than 9 lines on a chart; fewer are better. +- Do not remove axis titles unless it is clear to the user what is being visualized. diff --git a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md new file mode 100644 index 0000000000000..9c387b8e1738a --- /dev/null +++ b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md @@ -0,0 +1 @@ +- Remain consistent with one chart style if there are multiple instances of it on a page rather than using area and line charts interchangeably. diff --git a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md index 5fc68f4b16278..304ea55b19309 100644 --- a/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md +++ b/packages/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md @@ -1,43 +1,5 @@ -
-

- Area charts depict a time-series relationship. But unlike line charts, they can also visually represent - volume. Information is graphed on two axes, using data points connected by line segments. The area between - the axis and this line is commonly emphasized with color or shading for legibility. Most often area charts - compare two or more categories. The area chart is a highly performant visual. It uses a path based - rendering mechanism to render the area component. On hovering, the nearest x datapoint is identified and - the corresponding point is hovered. -

-

Area chart variants

-

Stacked area chart

-

- In stacked area chart, two or more data series are stacked vertically. It helps in easy comparison across - different dimensions. The callout on hover for stacked chart displays multiple values from the stack. The - callout can be customized to show single values or stacked values. Refer to the props - onRenderCalloutPerDataPoint and onRenderCalloutPerStack using which custom content for the - callout can be defined. -

-

Custom accessibility

-

- Area chart provides a bunch of props to enable custom accessibility messages. Use - xAxisCalloutAccessibilityData - and callOutAccessibilityData to configure x axis and y axis accessibility messages - respectively. -

-

Date Axis localization

-

- The axes support 2 ways of localization.
- 1. Javascript provided inbuilt localization for numeric and date axis. Specify the culture and - dateLocalizeOptions for date axis to define target localization. Refer the - - Javascript localization guide - - for usage.
- 2. Custom locale definition: The consumer of the library can specify a custom locale definition as - supported by d3 like this. - The date axis will use the date range and the multiformat specified in the definition to determine the - correct labels to show in the ticks. For example - If the date range is in days then the axis will show - hourly ticks. If the date range spans across months then the axis will show months in tick labels and so - on. Specify the custom locale definition in the timeFormatLocale prop. Refer to the Custom - Locale Date Axis example in line chart for sample usage. -

-
+Area charts are graphical representations of data that display quantitative data points connected by lines and filled with colors to create a visual representation of trends and patterns. The area between the line and the x-axis is colored, which helps in emphasizing the cumulative total or the overall magnitude of the data. They are a slight variation of single line charts, and generally can be used interchangeably. + +Stacked area charts are great at communicating how multiple data series relate to the total value. It illustrates how each series compares to the other in their contributions to the total. The baseline is moving in stacked area charts, rather than sharing a common baseline in overlapping areas. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/DonutChart/DonutChart.CustomAccessibility.Example.tsx b/packages/react-examples/src/react-charting/DonutChart/DonutChart.CustomAccessibility.Example.tsx index 4de1af47f3f15..94f08a635d76f 100644 --- a/packages/react-examples/src/react-charting/DonutChart/DonutChart.CustomAccessibility.Example.tsx +++ b/packages/react-examples/src/react-charting/DonutChart/DonutChart.CustomAccessibility.Example.tsx @@ -18,7 +18,7 @@ export class DonutChartCustomAccessibilityExample extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/DonutChart/DonutChartPage.tsx b/packages/react-examples/src/react-charting/DonutChart/DonutChartPage.tsx index 09358f8e26112..10d3a75feeb85 100644 --- a/packages/react-examples/src/react-charting/DonutChart/DonutChartPage.tsx +++ b/packages/react-examples/src/react-charting/DonutChart/DonutChartPage.tsx @@ -62,6 +62,16 @@ export class DonutChartPage extends React.Component {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md index 93c4396370ee6..bd4d6446dd39c 100644 --- a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md +++ b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md @@ -1,3 +1,19 @@ +### Layout + +- The donut chart’s behavior is simple in application. The data is ordered from largest to smallest in clockwise direction and users can single out individual segments for clarity. +- For high cardinality scenarios where the slices are very small, they can be grouped together to form a bigger slice to improve readability. +- The chart is centered in the available screen space. The default chart diameter is 140px and bar width is 16px. This matches the width of bars in bar charts to achieve balanced scale. The size can be adjusted with responsive chart behavior, where the size of the chart and bar diameter grows proportionally in units of 4px. +- Always try to balance the visual weight of the bars in relationship to the rest of the app. +- Segments are separated by a 2px gap to maximize readability. Segment labels should be always displayed for easier chart comprehension. +- Minimum padding around the chart is 16px. It also applies to the version with labels to accommodate space for labels. There is a 2px space between the chart and the label. The label is centered in relationship to the slice it describes. That can be offset if an overlap happens between 2 labels. + ### Content -DonutChart best practices content placeholder. +- The donut chart consists of segments arranged clockwise from large to small. The total circle equates to 100% of the data. The segments can use custom formatting, but all values must add up to 100%. Tiny segments may be grouped and shown visually as 'Others'. +- The label string inside the donut should be concise and contain numerical information with limited or no explanation. + +### Accessibility + +- Users "Enter" into the graph and can use both arrowing and tabbing to navigate through. +- The first tab stop will stop on the graph and give a description of what type of graph it is. +- Each segment can define its own accessibility label to help the user understand the data better. diff --git a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md new file mode 100644 index 0000000000000..2706081f1609e --- /dev/null +++ b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md @@ -0,0 +1 @@ +- Don't overuse donuts charts. They require a lot of space on the page and using more than one next to each other dilutes the intended message. diff --git a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md new file mode 100644 index 0000000000000..ef94b8e378ae1 --- /dev/null +++ b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md @@ -0,0 +1,2 @@ +- For scenarios with lots of categories, consider changing the type of graph to a stacked horizontal bar chart. +- We recommend donut charts over pie charts as they are more readable. diff --git a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md index 14d7cebde5883..d2f92068a5367 100644 --- a/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md +++ b/packages/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md @@ -1,17 +1,3 @@ -
-

- Donut charts show a percentage of a whole. They are circular statistical graphics divided into slices to - illustrate numerical proportion. Donut charts have an empty center where a numerical value can be shown. -

-

- The arc length of each data set in a donut is proportional to the quantity it represents, which can also - be expressed as a horizontal bar chart. -

-

- Note: Donut Charts typically represent two data points. Representing more data in a - circular chart (as seen in the second example) is known by the MADS team as a Pie Chart. -

-

- The arc labels are hidden by default. Set the hideLabels prop to false to show them. -

-
+Donut charts are used to show proportion, which expresses a partial value in comparison to a total value. These types of charts are best to show percentage of individual parts in comparison to a whole, where the change over time is not important to visualize. They are circular statistical graphics divided into slices to illustrate numerical proportion. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/GaugeChart/GaugeChart.doc.tsx b/packages/react-examples/src/react-charting/GaugeChart/GaugeChart.doc.tsx index 625746bdde537..288b60bdcd402 100644 --- a/packages/react-examples/src/react-charting/GaugeChart/GaugeChart.doc.tsx +++ b/packages/react-examples/src/react-charting/GaugeChart/GaugeChart.doc.tsx @@ -28,6 +28,8 @@ export const GaugeChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/GaugeChart/GaugeChartPage.tsx b/packages/react-examples/src/react-charting/GaugeChart/GaugeChartPage.tsx index 277a3d20d635e..b8c40bd5e1dad 100644 --- a/packages/react-examples/src/react-charting/GaugeChart/GaugeChartPage.tsx +++ b/packages/react-examples/src/react-charting/GaugeChart/GaugeChartPage.tsx @@ -50,6 +50,16 @@ export class GaugeChartPage extends React.Component {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md index 6023323846988..28dae94aa7f25 100644 --- a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md +++ b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md @@ -1,3 +1,28 @@ +### Layout + +The library recommends a few size width and height options for charts. Product teams must consider the complexity of the data to decide what size should be used in implementation. There are 6 size options for the gauge, ranging from very small to very large. The default size is medium, with a diameter of 140px and default bar width of 16px. All have a margin of 16px on all sides. + ### Content -GaugeChart best practices content placeholder. +- **Bar** This is the arc representing the semi-circle. +- **Min and max values** Used to represent minimum and maximum values for the data being measured. These can either be an absolute value or a percentage. +- **Data segment** This represents the current value as a part of the whole scale. For rating meter, it shows the relative scale of each segment. +- **Current value indicator / needle** Used to show user’s position on the semi-circular graph. +- **Chart value** This can be a number out of another (part to whole) or represented as a percentage. + +### Accessibility + +- Users 'Enter' into the graph and can use both arrowing and tabbing to navigate through. +- The first tab stop will stop on the graph and give a description of what type of graph it is. +- Each section of the graph is readable via a screen reader. + +### Customizing the chart + +- The diameter of the gauge depends upon the `width` and `height` props passed to the chart. If the props are omitted, a default diameter of `140px` will be used. +- To render a title above the gauge, set the `chartTitle` prop. +- The needle position depends upon the required `chartValue` prop. +- Use the required `segments` prop to divide the gauge into colored sections. These sections can have fixed sizes, or the users can choose to create a sweeping effect by varying the segment size with the `chartValue`. +- Set the `minValue` prop if the minimum value of the gauge is different than 0. A placeholder segment will be rendered if the `maxValue` prop is greater than the total size of the segments. +- To render an additional text below the `chartValue`, set the `sublabel` prop. +- To hide the minimum and maximum values of the gauge, set the `hideMinMax` prop. +- The `chartValue` prop is rendered as a percentage by default. Set the `chartVaueFormat` prop to `fraction` or a formatter function. diff --git a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md new file mode 100644 index 0000000000000..affea289b7c93 --- /dev/null +++ b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md @@ -0,0 +1 @@ +- Don’t add min and mix if you’re already representing the part to whole ratio within the gauge because it’s redundant. diff --git a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md new file mode 100644 index 0000000000000..2d528061c1bc0 --- /dev/null +++ b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md @@ -0,0 +1 @@ +- Display min and max values to the left and the right if you’re showing a percentage within the gauge. diff --git a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md index 7011bcc4a4cf0..7a3dd65da5548 100644 --- a/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md +++ b/packages/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md @@ -1,40 +1,11 @@ -
-

- Gauge chart measures the progress of a metric against its target and its primary components are a - speedometer and a needle. The speedometer usually consists of color-coded segments progressing value from - left to right. -

-

Implementation details

-
    -
  • - The diameter of the gauge depends upon the width and height props passed to - the chart. If the props are omitted, a default diameter of 140px will be used. -
    • -
  • - To render a title above the gauge, set the chartTitle prop. -
    • -
  • - The needle position depends upon the required chartValue prop. -
    • -
  • - Use the required segments prop to divide the gauge into colored sections. These sections - can have fixed sizes, or the users can choose to create a sweeping effect by varying the segment size - with the chartValue. -
    • -
  • - Set the minValue prop if the minimum value of the gauge is different than 0. A placeholder - segment will be rendered if the maxValue prop is greater than the total size of the - segments. -
    • -
  • - To render an additional text below the chartValue, set the sublabel prop. -
    • -
  • - To hide the minimum and maximum values of the gauge, set the hideMinMax prop. -
    • -
  • - The chartValue prop is rendered as a percentage by default. Set the chartVaueFormat prop to - 'fraction' or a formatter function. -
    • -
-
+A radial gauge chart uses a circular arc to show how a single value progresses toward a goal or a Key Performance Indicator (KPI). The gauge line (or needle) represents the goal or target value. The shading represents progress toward the goal. The value inside the arc represents the progress value. + +There are two types of gauge charts: Speedometer and rating meter. + +The speedometer measures a numerical value against a whole, like storage capacity. The needle is an optional component. The color of the segment representing the value being measured can be customized by product teams to suit certain scenarios or to align with branding colors. + +The rating meter shows status of the current value within a few predefined ranges or segments. The needle is a required component here. + +The segment sizes and colors can be customized by the product team to suit their needs. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChart.doc.tsx b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChart.doc.tsx index 63303d779518b..c03072b0cf374 100644 --- a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChart.doc.tsx @@ -45,6 +45,8 @@ export const GroupedVerticalBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChartPage.tsx b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChartPage.tsx index e334297f1ae7e..44e5eb472cf92 100644 --- a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/GroupedVerticalBarChartPage.tsx @@ -66,6 +66,16 @@ export class GroupedVerticalBarChart extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md index 4f714c6fb95d8..9e405fdac8598 100644 --- a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartBestPractices.md @@ -1,3 +1,14 @@ +### Layout + +A stacked bar chart is used to emphasize the composition of a category and how individual components contribute to it. +On the other hand, a grouped bar chart is used to compare distinct values across various categories or groups separately. + +Refer to Vertical Bar Chart page for common layout guidance. + ### Content -GroupedVerticalBarChart best practices content placeholder. +Refer to Vertical Bar Chart page for common content guidance. + +### Accessibility + +Refer to Vertical Bar Chart page for common accessibility guidance. diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDonts.md b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDonts.md new file mode 100644 index 0000000000000..45396ae5c058e --- /dev/null +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDonts.md @@ -0,0 +1 @@ +- Refer to Vertical Bar Chart page for common don'ts. diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDos.md b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDos.md new file mode 100644 index 0000000000000..f5ddf35e0a21e --- /dev/null +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartDos.md @@ -0,0 +1 @@ +- Refer to Vertical Bar Chart page for common dos. diff --git a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartOverview.md b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartOverview.md index 947e8b198ffc5..a3e2e85d7bdbb 100644 --- a/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartOverview.md +++ b/packages/react-examples/src/react-charting/GroupedVerticalBarChart/docs/GroupedVerticalBarChartOverview.md @@ -1,13 +1,5 @@ -
-

- Grouped vertical bar chart is slightly different than a vertical stacked bar chart. In a vertical stacked - bar chart, the bars are stacked one on top of the other. In a grouped vertical bar chart, the vertical - bars are aligned next to each other in groups. In stacked bar chart, the reference point for each bar is - either the x axis or another bar in the stack. For grouped vertical bar chart, each bar has x axis as the - reference point. Having a common reference point helps in better comparison between different values in - the chart. -

-

- The bar labels are shown by default. Set the hideLabels prop to hide them. -

-
+A grouped vertical bar chart displays multiple series of data as a group of bars, with each bar denoting a category. The bars are grouped together side by side, with each group denoting a different series. + +Effectively, a grouped vertical bar chart can slice data across 2 dimensions - (1) A dimension along the x axis and (2) Groups within the first dimension. And the y-axis plots the values of each category. Each bar in a group is colored differently to differentiate among categories within the group. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChart.doc.tsx b/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChart.doc.tsx index 6f691d445ab30..41b8663aa88d1 100644 --- a/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChart.doc.tsx +++ b/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChart.doc.tsx @@ -26,6 +26,8 @@ export const HeatMapChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChartPage.tsx b/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChartPage.tsx index b5723d86c159d..ced96c114205e 100644 --- a/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChartPage.tsx +++ b/packages/react-examples/src/react-charting/HeatMapChart/HeatMapChartPage.tsx @@ -47,6 +47,16 @@ export class HeatMapChart extends React.Component { {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md index bb2bd454397a2..417b5b34ae9ec 100644 --- a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md +++ b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartBestPractices.md @@ -1,3 +1,31 @@ +### Layout + +Heatmaps are flexible in nature. The chart can support a minimum 2x2 grid through a maximum of 10x10 grid. The nodes should span and reflow with the overall width and height of your composition. + ### Content -HeatMapChart best practices content placeholder. +The user has freedom to either choose a sequential palette or a range of colors that best represent the range of values. For example, AQI values of regions in a country could be represented in shades of green, orange and red based on prescribed health limits of the air quality. + +### Customizing the chart + +#### Defining Color scale + +The color palette for a heat map chart is defined by a domain/range combination. The domain consists of values in the chart columns. It is an array of numbers. See `domainValuesForColorScale`. The range is an array `rangeValuesForColorScale` of colors in hex format. The graph creates a mapping between each value from domain to range. For all values in the domain, an equivalent interpolation is drawn in the range of color scale. For eg: if the domain is [0,500,900] and range is [green, blue, red], then [0, 500] is mapped in the range [green, blue] and [500, 900] in the range [blue, red]. + +#### Data formatting + +Use the following formatters based on the type of axis. + +- For date x axis use: `xAxisDateFormatString` +- For date y axis use: `yAxisDateFormatString` +- For numeric x axis use: `xAxisNumberFormatString` +- For numeric y axis use: `yAxisNumberFormatString` +- For string x axis use: `xAxisStringFormatter` +- For string y axis use: `yAxisStringFormatter` + +#### Axis localization + +The chart axes support 2 ways of localization. + +1. JavaScript provided inbuilt localization for numeric and date axis. Specify the culture and `dateLocalizeOptions` for date axis to define target localization. Refer the [Javascript localization guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString) for usage. +2. Custom locale definition: The consumer of the library can specify a custom locale definition as supported by d3 [like this](https://github.com/d3/d3-time-format/blob/main/locale/en-US.json). The date axis will use the date range and the multiformat specified in the definition to determine the correct labels to show in the ticks. For example - If the date range is in days, then the axis will show hourly ticks. If the date range spans across months, then the axis will show months in tick labels and so on. Specify the custom locale definition in the `timeFormatLocale` prop. Refer to the Custom Locale Date Axis example in line chart for sample usage. diff --git a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDonts.md b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDonts.md new file mode 100644 index 0000000000000..1859e849f54d3 --- /dev/null +++ b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDonts.md @@ -0,0 +1 @@ +- Heatmap should not be used as a table as the color coding is tied to data intensity. diff --git a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDos.md b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDos.md new file mode 100644 index 0000000000000..9f73259a8351e --- /dev/null +++ b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartDos.md @@ -0,0 +1 @@ +- Use sequential or divergent color palettes. diff --git a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartOverview.md b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartOverview.md index abaf7fbb0c10c..4cf54e0128d0c 100644 --- a/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartOverview.md +++ b/packages/react-examples/src/react-charting/HeatMapChart/docs/HeatMapChartOverview.md @@ -1,54 +1,3 @@ -
-

- Heat Map Chart is a two-dimensional visual representation of data, where values are encoded in colors, - delivering a convenient, insightful view of information. Essentially, this chart type is a data table with - rows and columns denoting different sets of categories. Each cell in the table can contain a numerical or - logical value that determines the cell color based on a given color palette. -

-

Defining Color scale

-

- The color palette for a heat map chart is defined by a domain/range combination. The domain consists of - values in the chart columns. It is an array of numbers. See domainValuesForColorScale. The - range is an array rangeValuesForColorScale of colors in hex format. The graph creates a - mapping between each value from domain to range. For all values in the domain, an equivalent interpolation - is drawn in the range of color scale. For eg: if the domain is [0,500,900] and range is [green, blue, - red], then [0, 500] is mapped in the range [green, blue] and [500, 900] in the range [blue, red], -

-

Data formatting

-

Use the following formatters based on the type of axis.

-

- For date x axis use: xAxisDateFormatString -

-

- For date y axis use: yAxisDateFormatString -

-

- For numeric x axis use: xAxisNumberFormatString -

-

- For numeric y axis use: yAxisNumberFormatString -

-

- For string x axis use: xAxisStringFormatter -

-

- For string y axis use: yAxisStringFormatter -

-

Date Axis localization

-

- The axes support 2 ways of localization.
- 1. Javascript provided inbuilt localization for numeric and date axis. Specify the culture and - dateLocalizeOptions for date axis to define target localization. Refer the - - Javascript localization guide - - for usage.
- 2. Custom locale definition: The consumer of the library can specify a custom locale definition as - supported by d3 like this. - The date axis will use the date range and the multiformat specified in the definition to determine the - correct labels to show in the ticks. For example - If the date range is in days then the axis will show - hourly ticks. If the date range spans across months then the axis will show months in tick labels and so - on. Specify the custom locale definition in the timeFormatLocale prop. Refer to the Custom - Locale Date Axis example in line chart for sample usage. -

-
+A heatmap is a 2D visualization that uses color to represent magnitude or intensity of values in the dataset. Generally, the color uses a sequential palette and corresponds to the value’s relative position within the represented ranges. This generally means larger values have darker colors. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChart.doc.tsx b/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChart.doc.tsx index 0187f1fb900df..98e6ecd857133 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChart.doc.tsx @@ -53,6 +53,8 @@ export const HorizontalBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChartPage.tsx b/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChartPage.tsx index 6a05e30ab46db..0f4b992775e2f 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/HorizontalBarChartPage.tsx @@ -71,6 +71,16 @@ export class HorizontalBarChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md index 5bc8b76309a15..a376526f7ecf2 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartBestPractices.md @@ -1,3 +1,29 @@ +### Layout + +Use a horizontal bar graph to compare between different values that are hierarchically equivalent. The rectangular bar length is proportional to the values they represent. There will always be a maximum data value (color) representing the total length. + +Horizontal bar chart can be of 2 types - + +- **Absolute scale** the length of the bar is proportional to the biggest value for the category. +- **n/M scale** the length of the bar is determined by the total/target value of the specific bar. As a result, 2 adjacent bars can have different data scales and not be comparable. This aspect should be kept in mind while using this chart type. See HorizontalBarChart benchmark example to see the behavior. Each bar has a different scale - 100, 200 and 50 units. + ### Content -HorizontalBarChart best practices content placeholder. +- **Title/Label** The label for the bar. It is displayed above the bar and can represent longer texts. +- **Bar segment** The bar segment represents the current value of the category. For n/M variant there is a placeholder segment to show the left-over values. +- **Bar value** The value of the bar is represented on the right side. This can be absolute or percentage format. This can also be in fractional form representing current value out of total value. See the chartDataMode property to use it. +- **Benchmark** The benchmark value is shown as an inverted triangle in the chart. + +### Accessibility + +- Bar graphs should be flexible to their containers. They will change widths to fit their environment. +- Each section of the bar chart is readable via screen readers. The user can navigate through the entire bar graph by using the tab keys. +- The chart reflows to accommodate zooming in to 400%. + +### Customizing the chart + +- **Bar chart custom data** This property allows customizing the right-side data part of the chart. See the usage of `barChartCustomData` prop in custom callout variant. +- **Custom hover callout** See `onRenderCalloutPerHorizontalBar` prop to customize the hover callout. + Set the `chartDataMode` as number, fraction or percentage to specify how numerical values will be shown on the chart. +- **Benchmark data** Set the data attribute of `IChartDataPoint` to specify the benchmark value. The benchmark value is shown as an inverted triangle in the chart. +- **AbsoluteScale variant** The bar labels are shown by default in the absolute-scale variant. Set the `hideLabels` prop to hide them. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDonts.md b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDonts.md new file mode 100644 index 0000000000000..0adbceeae28ee --- /dev/null +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDonts.md @@ -0,0 +1,2 @@ +- Avoid having more than 20 bars in the chart. +- The n/M variant should be used only when a value has to be compared against its target value. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDos.md b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDos.md new file mode 100644 index 0000000000000..b23ae8f3d2ca2 --- /dev/null +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartDos.md @@ -0,0 +1,2 @@ +- Use horizontal bar chart if the length of labels is longer. +- Numerical units on labels are represented through abbreviations. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartOverview.md b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartOverview.md index f6ed14840b737..6e08ca0df212f 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartOverview.md +++ b/packages/react-examples/src/react-charting/HorizontalBarChart/docs/HorizontalBarChartOverview.md @@ -1,32 +1,3 @@ -
-

- Use a horizontal bar graph to compare between different values that are hierarchically equivalent. The - rectangular bar length is proportional to the values they represent. There will always be a maximum data - value (color) that is used to represent the total length. -

-

Numerical values are represented through abbreviations.

-

Bar chart custom data

-

- This property allows customizing the right side data part of the chart. See the usage of - barChartCustomData - prop in custom callout variant. -

-

Custom hover callout

-

- See onRenderCalloutPerHorizontalBar prop to customize the hover callout. -

-

- Set the chartDataMode as number, fraction or percentage to specify how numerical values will - be shown on the chart. -

-

Benchmark data

-

- Set the data attribute of IChartDataPoint to specify the benchmark value. The benchmark value - is shown as an inverted triangle in the chart. -

-

AbsoluteScale variant

-

- The bar labels are shown by default in the absolute-scale variant. Set the hideLabels prop to - hide them. -

-
+A horizontal bar chart is a chart that presents categorical data with rectangular bars with lengths proportional to the values they represent. This type of chart is particularly useful when the intention is to show comparisons among various categories and the labels for those categories are long. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxis.doc.tsx b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxis.doc.tsx index 11b8ce241173b..26a56dd970085 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxis.doc.tsx +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxis.doc.tsx @@ -37,6 +37,8 @@ export const HorizontalBarChartWithAxisPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxisPage.tsx b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxisPage.tsx index f60e805e634d5..035c367cb2857 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxisPage.tsx +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/HorizontalBarChartWithAxisPage.tsx @@ -62,6 +62,16 @@ export class HorizontalBarChartWithAxisPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md index 87298428eb4c4..4f9c25ed8ceee 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisBestPractices.md @@ -1,3 +1,31 @@ +### Layout + +The default bar height is 16px. For dense data, it can be as thin as 8px high. Always consider the visual weight of the bars in relationship to the rest of the app before choosing this type of chart. + +The padding around the bar chart is a default of 8px from the x and y-axis container. This gives enough room for additional content like label values to display properly without overlapping on to the Y-axis ticks. A 2:1 spacing is maintained between all the bars in the graph so that space between two bars is always two times the bar height. This helps to ensure that the graph is not overpowering other data visualizations. For charts that display monetary values, the dollar symbol should be displayed as part of the total value. Also call out the currency in the chart title to provide additional context. Chart title can be used to communicate currency when the total labels are hidden. + +The chart can accommodate unusually long labels by shrinking the bars without distorting the visual layout. + ### Content -HorizontalBarChartWithAxis best practices content placeholder. +- **Bar segment** Bar segments make up a bar chart. Standard size options are: 8px, 16px, and 24px with 16px being the default. +- **Value labels** (Optional) - Off by default with the option to toggle on in case the data visualization needs to communicate label values to users. + +### Accessibility + +- Bar graphs should be flexible to their containers. They will change width and height to fit their environment. +- Type truncation should happen when the total value exceeds one thousand including 1 decimal place for the hundreds. For example, display full value for 600, 983, or 19.53. Truncate 6,000 to 6.0K, 9,801 to 9.8K, and 100,900 to 100.9K. +- All the bars of the graph are accessible by screen readers and keyboard navigation using Up and Down arrow keys. + +### Customizing the chart + +The chart provides an option to select a color scale based on the range of x values. Similar x values will end up having similar color. Use the colors attribute to define the color scale. + +Use `useSingleColor` to use a single color for all bars. + +See `onRenderCalloutPerHorizontalBar` prop to customize the hover callout. + +If the y data points are of string type there are 2 modes to view them + +1. truncate yaxis labels using `showYAxisLablesTooltip` +2. shrink the x axis and display the complete labels using `expandYAxisLabels` property. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDonts.md b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDonts.md new file mode 100644 index 0000000000000..e7b74ebb087c2 --- /dev/null +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDonts.md @@ -0,0 +1 @@ +- Don't keep the bar values in random order. Horizontal bar chart is most effective if the bars are sorted in either ascending or descending order. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDos.md b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDos.md new file mode 100644 index 0000000000000..2cbae14e28a92 --- /dev/null +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisDos.md @@ -0,0 +1,2 @@ +- Try to keep the number of bars in the chart between 3 and 20 to maximize readability. +- Use this chart if the bar labels are very long. diff --git a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisOverview.md b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisOverview.md index cf0133b4a742c..b07e128488e4f 100644 --- a/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisOverview.md +++ b/packages/react-examples/src/react-charting/HorizontalBarChartWithAxis/docs/HorizontalBarChartWithAxisOverview.md @@ -1,26 +1,6 @@ -
-

- Use a horizontal bar graph to compare between different values that are hierarchically equivalent. The - rectangular bar length is proportional to the values they represent. There will always be a maximum data - value (color) that is used to represent the total length. -

-

- The bar widths are proportional to the number of bars and space available within the charting area. The - bar width can be changed using the barWidth property. -

-

Implementation details

-

- The chart provides an option to select a color scale based on the range of x values. Similar x values will - end up having similar color. Use the colors attribute to define the color scale. -

-

- Use useSingleColor to use a single color for all bars. -

-

- See onRenderCalloutPerHorizontalBar prop to customize the hover callout. -

-

- If the y data points are of String there are 2 modes to view them, the first to truncates yaxis labels - using showYAxisLablesTooltip and the second enables to view the complete labels using expandYAxisLabels. -

-
+A horizontal bar chart is a chart that presents categorical data with rectangular bars with lengths proportional to the values they represent. This type of chart is particularly useful when the intention is to show comparisons among various categories and the labels for those categories are long. + +Horizontal bar chart with axis is a version of horizontal bar chart that has the x and y axis present. +This chart is same as the vertical bar chart except that the bars are aligned horizontally. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/Legends/docs/LegendsBestPractices.md b/packages/react-examples/src/react-charting/Legends/docs/LegendsBestPractices.md index c774b97f517c5..b74c2bb7ac808 100644 --- a/packages/react-examples/src/react-charting/Legends/docs/LegendsBestPractices.md +++ b/packages/react-examples/src/react-charting/Legends/docs/LegendsBestPractices.md @@ -1,3 +1,20 @@ ### Content -Legend best practices content placeholder. +#### Legend Actions + +The legends are selectable. Action to be performed upon clicking a certain legend can be customized. Refer to the `action`, `hoverAction` and `onMouseOutAction` properties to customize these actions. + +#### Legend shapes and colors + +Use shape to customize the legend shape. Legend support different shapes like rectangle, triangle, diamond, circle, pyramid, hexagon. Use `stripePattern` to have stripe pattern applied to the legend shape. If `isLineLegendInBarChart` is set, the legend will have the shape of a line with height 4px. All other legend shapes have a height of 12px. + +#### Legend overflow + +`overflowText` describes the overflow text. `overflowProps` can be used to set properties like overflow layout direction to be stacked/vertical, overflow side to be start/end, overflow styling and more. + +Legends can be wrapped to the next line if the labels are very long. + +### Accessibility + +- Legends are readable via screen readers. The user can navigate through the entire legend section by using the Left and Right arrow keys. +- Legends can reflow to accommodate zooming in to 400%. diff --git a/packages/react-examples/src/react-charting/Legends/docs/LegendsOverview.md b/packages/react-examples/src/react-charting/Legends/docs/LegendsOverview.md index 2b7925ee7765b..4017e56e3747c 100644 --- a/packages/react-examples/src/react-charting/Legends/docs/LegendsOverview.md +++ b/packages/react-examples/src/react-charting/Legends/docs/LegendsOverview.md @@ -1,25 +1,3 @@ -
-

- A legend describes each of the component of the chart. The legends wrap based upon the space available for - them. If there is not enough space to show all legends on a single line, the legends fall into an overflow - menu. A button is shown to open the overflow menu and indicating the number of legends in it. -

-

Legend Actions

-

- The legends are selectable. Action to be performed upon clicking a certain legend can be customized. Refer - to the action, hoverAction and onMouseOutAction properties to customize these actions. -

-

Legend shapes and colors

-

- Use shape to customize the legend shape. Legend support different shapes like rectangle, - triangle, diamond, circle, pyramid, hexagon etc. Use stripePattern to have stripe pattern - applied to the legend shape. If isLineLegendInBarChart is set, the legend will have the shape - of a line with height 4px. All other legend shapes have a height of 12px -

-

Legend overflow

-

- overflowText describes the overflow text. overflowProps can be used to set - properties like overflow layout direction to be stacked/vertical, overflow side to be start/end, overflow - styling and more. -

-
+A legend describes data visualized in the chart. The legends can wrap based upon the space available for them. If there is not enough space to show all legends on a single line, the legends fall into an overflow menu. A button is shown to open the overflow menu and displays the number of legends in it. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/LineChart/LineChart.doc.tsx b/packages/react-examples/src/react-charting/LineChart/LineChart.doc.tsx index 2c8ee7f12a41d..bce8f8dd2c8e0 100644 --- a/packages/react-examples/src/react-charting/LineChart/LineChart.doc.tsx +++ b/packages/react-examples/src/react-charting/LineChart/LineChart.doc.tsx @@ -70,7 +70,6 @@ export const LineChartPageProps: IDocPageProps = { bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartBestPractices.md'), dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartDos.md'), donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md'), - accessibility: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartAccessibility.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/LineChart/LineChartPage.tsx b/packages/react-examples/src/react-charting/LineChart/LineChartPage.tsx index ed37c728cf35e..9b594e51234b5 100644 --- a/packages/react-examples/src/react-charting/LineChart/LineChartPage.tsx +++ b/packages/react-examples/src/react-charting/LineChart/LineChartPage.tsx @@ -99,11 +99,6 @@ export class LineChartPage extends React.Component {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md')} } - accessibility={ - - {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/LineChart/docs/LineChartAccessibility.md')} - - } /> ); } diff --git a/packages/react-examples/src/react-charting/LineChart/docs/LineChartBestPractices.md b/packages/react-examples/src/react-charting/LineChart/docs/LineChartBestPractices.md index 9881deee2a8c2..1c2dfc838d9be 100644 --- a/packages/react-examples/src/react-charting/LineChart/docs/LineChartBestPractices.md +++ b/packages/react-examples/src/react-charting/LineChart/docs/LineChartBestPractices.md @@ -1,3 +1,47 @@ +### Layout + +Padding on the left and right of the chart is determined by the x-axis labels - it should start and end at or nearly at the first and last tick mark. The minimum padding is 8px. + ### Content -LineChart best practices content placeholder. +- **Line** A line represents a set of values from the same data set. Each line takes on a new swatch in the data visualization library to distinguish it from others. 2px wide with rounded endpoints; no rounding of joints to avoid data misrepresentation. 6px border behind line with rounded endpoints that match background color to improve legibility and readability when two or more lines cross each other. +- **Pinpoints** Optional: Pinpoints are built into each line component and can be toggled on to reveal a unique shape to remove reliance on colors as sole identifier of data set. Size: 8px. Off by default with the option to toggle it on. + +### Accessibility + +- Users "Enter" into the graph and can use both arrow and tab keys to navigate through. +- The first tab stop will stop on the graph and give a description of what type of graph it is. +- Each section of the graph is readable via screen readers. The user can navigate through the entire area plot by using Left and Right arrow keys. + +### Customizing the chart + +Use a line graph to visualize data sets over a period of time for an individual or group of items. The number of lines (data sets) depend on the attributes selected during the report creation. + +The line graph thickness will vary depending on the number of data sets and data increments. + +#### Event annotations + +Event annotations are used to highlight events and annotate them using messages. Annotations are represented by vertical line markers to mark the date and callouts to represent the message. Events can be added by using `eventAnnotationProps` prop. Each event contains a `date`, `event message` and event details callout callback `onRenderCard` + +#### Gaps + +A line chart can have gaps/breaks in between. This is to represent missing data. The gaps can also be replaced with dashed or dotted lines for specific scenarios, say to represent low confidence predictions for a time series forecast graph. Gaps can be added by using `gaps` prop. A gap is denoted by `startIndex` and `endIndex` datapoints in the line. A line will be drawn till the `startIndex` and skipped for `endIndex - startIndex` number of datapoints. A line can have as many gaps as possible. + +#### Line border + +Each line in the chart can contain a 2 px border for better highlighting of the line when there are multiple items in the chart. The border will have color of the background theme. Lines will be highlighted in order of their appearance in legends. Line border is a highly suggested style that you should apply to make multiple lines more distinguishable from each other. Use `lineBorderWidth` prop present inside `lineOptions` to enable it. + +#### Lines with large dataset + +We use a path-based rendering technique to show datasets with large number of points (greater than 1k). Using this technique datasets with over 10k points can be rendered with high performance. Enable this rendering method by setting the `optimizeLargeData` prop to true. Refer to the [performance section](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md#performance) to know more about our performance benchmarks. + +#### Custom accessibility + +Line chart provides a bunch of props to enable custom accessibility messages. Use `xAxisCalloutAccessibilityData` and `callOutAccessibilityData` to configure x axis and y axis accessibility messages, respectively. + +#### Axis localization + +The chart axes support 2 ways of localization. + +1. JavaScript provided inbuilt localization for numeric and date axis. Specify the culture and `dateLocalizeOptions` for date axis to define target localization. Refer the [Javascript localization guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString) for usage. +2. Custom locale definition: The consumer of the library can specify a custom locale definition as supported by d3 [like this](https://github.com/d3/d3-time-format/blob/main/locale/en-US.json). The date axis will use the date range and the multiformat specified in the definition to determine the correct labels to show in the ticks. For example - If the date range is in days, then the axis will show hourly ticks. If the date range spans across months, then the axis will show months in tick labels and so on. Specify the custom locale definition in the `timeFormatLocale` prop. Refer to the Custom Locale Date Axis example in line chart for sample usage. diff --git a/packages/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md b/packages/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md index 0862bff3f602f..9e2044fa30a5e 100644 --- a/packages/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md +++ b/packages/react-examples/src/react-charting/LineChart/docs/LineChartDonts.md @@ -1,4 +1,2 @@ -- Dont1 -- Dont2 -- Dont3 -- Dont4 +- Don't use curved lines to represent data as it may show the data incorrectly. +- While multiple lines on a line chart can provide some additional information and clarity, too many lines can make the chart difficult to read. Don't use for more than 9 data points. Too many lines make it hard to read. diff --git a/packages/react-examples/src/react-charting/LineChart/docs/LineChartDos.md b/packages/react-examples/src/react-charting/LineChart/docs/LineChartDos.md index 8444f381d03d7..167769b9d0b13 100644 --- a/packages/react-examples/src/react-charting/LineChart/docs/LineChartDos.md +++ b/packages/react-examples/src/react-charting/LineChart/docs/LineChartDos.md @@ -1,4 +1 @@ -- Do1 -- Do2 -- Do3 -- Do4 +- Use line chart to portray trends. diff --git a/packages/react-examples/src/react-charting/LineChart/docs/LineChartOverview.md b/packages/react-examples/src/react-charting/LineChart/docs/LineChartOverview.md index 20ea131f4f632..79ccb918b9cbb 100644 --- a/packages/react-examples/src/react-charting/LineChart/docs/LineChartOverview.md +++ b/packages/react-examples/src/react-charting/LineChart/docs/LineChartOverview.md @@ -1,65 +1,5 @@ -
-

- Use a line graph to visualize data sets over a period of time for an individual or group of items. The - amount of lines (data sets) depend on the attributes selected during the report creation. -

-

The line graph thickness will vary depending on the number of data sets and data increments.

+A line chart is a visual representation of data that shows the relationship between two variables, often used to show trends over a period of time or number line. Line charts plot data at regular intervals connected by lines. Multi-line charts enable comparison between multiple series over the same x domain. -

Variant details

-

Event annotations

-

- Event annotations are used to highlight events and annotate them using messages. Annotations are - represented by vertical line markers to mark the date and callouts to represent the message. Events can be - added by using eventAnnotationProps prop. Each event contains a - date, event message and event details callout callback - onRenderCard -

-

Gaps

-

- A line chart can have gaps/breaks in between. This is to represent missing data. The gaps can also be - replaced with dashed or dotted lines for specific scenarios, say to represent low confidence predictions - for a time series forecast graph. Gaps can be added by using gaps prop. A gap is denoted by - startIndex and - endIndex datapoints in the line. A line will be drawn uptil the startIndex and skipped for - endIndex - startIndex number of datapoints. A line can have as many gaps as possible. -

-

Line border

-

- Each line in the chart can contain a 2 px border for better highlighting of the line when there are - multiple items in the chart. The border will have color of the background theme. Lines will be highlighted - in order of their appearance in legends. Line border is a highly suggested style that you should apply to - make multiple lines more distinguishable from each other. Use lineBorderWidth prop present - inside - lineOptions to enable it. -

-

Lines with large dataset

-

- We use a path based rendering technique to show datasets with large number of points (greater than 1k). - Using this technique datasets with over 10k points can be rendered easily. Enable this rendering method by - setting the optimizeLargeData prop to true. -

-

Custom accessibility

-

- Line chart provides a bunch of props to enable custom accessibility messages. Use - xAxisCalloutAccessibilityData - and callOutAccessibilityData to configure x axis and y axis accessibility messages - respectively. -

-

Date Axis localization

-

- The axes support 2 ways of localization.
- 1. Javascript provided inbuilt localization for numeric and date axis. Specify the culture and - dateLocalizeOptions for date axis to define target localization. Refer the - - Javascript localization guide - - for usage.
- 2. Custom locale definition: The consumer of the library can specify a custom locale definition as - supported by d3 like this. - The date axis will use the date range and the multiformat specified in the definition to determine the - correct labels to show in the ticks. For example - If the date range is in days then the axis will show - hourly ticks. If the date range spans across months then the axis will show months in tick labels and so - on. Specify the custom locale definition in the timeFormatLocale prop. Refer to the Custom - Locale Date Axis example in line chart for sample usage. -

-
+Time intervals are traditionally mapped to the horizontal axis. Data values are mapped to the vertical axis. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChart.doc.tsx b/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChart.doc.tsx index 765bd0e8d0165..4edf75d1e80d3 100644 --- a/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChart.doc.tsx @@ -37,6 +37,8 @@ export const MultiStackedBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChartPage.tsx b/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChartPage.tsx index d513fe4a39758..d180b881f6a4e 100644 --- a/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/MultiStackedBarChartPage.tsx @@ -58,6 +58,16 @@ export class MultiStackedBarChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md index 59f36a547e22d..82d45506a319a 100644 --- a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartBestPractices.md @@ -1,3 +1,24 @@ +### Layout + +The multistacked bar chart is available for actual scale and n/M scale. + +Refer to horizontal bar chart page for common layout guidance. + ### Content -MultiStackedBarChart best practices content placeholder. +The multistacked bar chart has legends component to interact with individual categories. + +Refer to horizontal bar chart page for common content guidance. + +### Accessibility + +Refer to horizontal bar chart page for common accessibility guidance. + +### Customizing the chart + +- Multi-stacked bar chart takes `data` attribute which is of type `IChartDataPoint[][]`. It will render the chart based upon the values given to this attribute. +- MultiStackedBarChart has an option `hideRatio` which shows/hides the ratio on top right of the chart. It is a `boolean[]`, one bool for each bar group. This value is applicable only when there are 2 datapoints in the chart. Similarly, there is an option `hideDenominator` to hide the denominator of the ratio if it is enabled. +- If a datapoint is marked as `placeHolder` there will be no corresponding legend. The default color of placeholder data is `tertiary grey`. +- If a chart in MultiStackedBarChart shows ratio or number, legends are not displayed for that chart and vice-versa. +- A number is displayed on the top of stacked bar chart if it has only one data point. This number shown is the datapoint that is passed to the chart. +- The bar labels are shown by default in the absolute-scale variant. Set the `hideLabels` prop to hide them. diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDonts.md b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDonts.md new file mode 100644 index 0000000000000..0adbceeae28ee --- /dev/null +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDonts.md @@ -0,0 +1,2 @@ +- Avoid having more than 20 bars in the chart. +- The n/M variant should be used only when a value has to be compared against its target value. diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDos.md b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDos.md new file mode 100644 index 0000000000000..1f257b53955f1 --- /dev/null +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartDos.md @@ -0,0 +1,2 @@ +- Use multistacked horizontal bar chart if there are multiple groups of subcategories that cannot be displayed on the stacked bar chart. +- Very small values are shown as 1% wide sections on the bar. diff --git a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartOverview.md b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartOverview.md index 331a62db42e5b..45ba7a73143fe 100644 --- a/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartOverview.md +++ b/packages/react-examples/src/react-charting/MultiStackedBarChart/docs/MultiStackedBarChartOverview.md @@ -1,35 +1,7 @@ -
-

- StackedBarChart shows the data in a bar format. It has two variations: single stacked and multi-stacked. - Below are a few points that will help you understand the multi stacked bar chart better: -

-

Multi stacked bar chart

-
    -
  • - Multi-stacked bar chart takes 'data' attribute which is of type IChartDataPoint[][]. It will render the - chart based upon the values given to this attribute. -
    • -
  • - MultiStackedBarChart has an option hideRatio which shows/hides the ratio on top right of - the chart. It is a boolean[], one bool for each bar group. This value is applicable only when there are - 2 datapoints in the chart. Similarly there is an option hideDenominator to hide the - denominator of the ratio if it is enabled. -
    • -
  • - If a datapoint is marked as placeHolder there will be no corresponding legend. The default - color of placeholder data is tertiary grey. -
    • -
  • - If a chart in MultiStackedBarChart shows ratio or number, legends are not displayed for that chart and - vice-versa. -
    • -
  • - A number is displayed on the top of stacked bar chart if it has only one data point. This number shown - is the datapoint that is passed to the chart. -
    • -
  • - The bar labels are shown by default in the absolute-scale variant. Set the hideLabels prop - to hide them. -
    • -
-
+Horizontal multistacked bar chart displays multiple series of data as stacked bars, with each bar representing a category. The bars are stacked alongside each other, with the length of each bar representing the value of the category of the series. + +Additionally, it allows grouping subcategories. Each subcategory can be displayed in a bar of its own to provide further breakdown. + +The multistacked bar chart is a 100% chart. This means the sum of all categories sums up to 100% width of the chart. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/PieChart/docs/PieChartBestPractices.md b/packages/react-examples/src/react-charting/PieChart/docs/PieChartBestPractices.md index f8da27b9ac64f..9c7d4f3514482 100644 --- a/packages/react-examples/src/react-charting/PieChart/docs/PieChartBestPractices.md +++ b/packages/react-examples/src/react-charting/PieChart/docs/PieChartBestPractices.md @@ -1,3 +1,14 @@ +### Layout + +- For high cardinality scenarios where the slices are very small, they can be grouped together to form a bigger chunk. +- Values should always be displayed for easier chart comprehension. There is a 2px space between the chart and the text. The value is centered in relationship to the slice it describes. That can be offset if an overlap happens. +- Minimum padding is 16px around the chart. That applies to the version with title to accommodate space for values. The chart is centered within the area. +- The slice labels should be short and concise as they take additional screen space outside the pie visual. + ### Content -PieChart best practices content placeholder. +Segments should be ordered from largest to smallest in clockwise direction. + +Pie Labels for each segment (optional) + +Divider gaps between segments to improve readability. diff --git a/packages/react-examples/src/react-charting/PieChart/docs/PieChartOverview.md b/packages/react-examples/src/react-charting/PieChart/docs/PieChartOverview.md index 5a9cefe420031..a5e91940b0903 100644 --- a/packages/react-examples/src/react-charting/PieChart/docs/PieChartOverview.md +++ b/packages/react-examples/src/react-charting/PieChart/docs/PieChartOverview.md @@ -1,5 +1,5 @@ -
-

- Pie Chart needs documentation. -

-
+A pie chart is a circular visual representation used to illustrate the composition or distribution of a single data set. It divides the whole data into segments, resembling slices of a pie, where each slice represents a distinct category or component. The size of each slice is directly proportional to the quantity it represents within the entire dataset. + +Pie chart does not have the benefits of donut chart and, therefore, it is rarely chosen. Pie chart has an advantage in certain reading scenarios only, where users want to compare the ratio of angles or areas of the slices. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/SankeyChart/SankeyChart.doc.tsx b/packages/react-examples/src/react-charting/SankeyChart/SankeyChart.doc.tsx index ffd93a84215be..5ea2c8281031a 100644 --- a/packages/react-examples/src/react-charting/SankeyChart/SankeyChart.doc.tsx +++ b/packages/react-examples/src/react-charting/SankeyChart/SankeyChart.doc.tsx @@ -28,6 +28,8 @@ export const SankeyChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/SankeyChart/SankeyChartPage.tsx b/packages/react-examples/src/react-charting/SankeyChart/SankeyChartPage.tsx index adc4543120386..7b0a4f4d1001e 100644 --- a/packages/react-examples/src/react-charting/SankeyChart/SankeyChartPage.tsx +++ b/packages/react-examples/src/react-charting/SankeyChart/SankeyChartPage.tsx @@ -50,6 +50,16 @@ export class SankeyChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md index 3605ab0e5f5f9..bc3c487862a02 100644 --- a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md +++ b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartBestPractices.md @@ -1,3 +1,16 @@ +### Layout + +Sankey charts require a minimum of 2 layers/ column groups to compare and can go up to a maximum of 4. More than 4 layers start making the chart overwhelming. + ### Content -SankeyChart best practices content placeholder. +- Node with title of data +- Stream representing value connecting boxes. +- Streams have a color gradient from their source to the destination. +- Hover states over both nodes and streams + +### Accessibilit + +In the case where data equates to 1 (which is 4px) the node does not show content. The text is shown when a user hovers over the node. + +In the case where the node height reaches a minimum of 24 pixels, the title and number are on the same line. If the title is longer it is truncated. diff --git a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDonts.md b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDonts.md new file mode 100644 index 0000000000000..79d742f37a2ef --- /dev/null +++ b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDonts.md @@ -0,0 +1 @@ +- Avoid having more than 4 layers in the Sankey chart. diff --git a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDos.md b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDos.md new file mode 100644 index 0000000000000..ccd37af90e087 --- /dev/null +++ b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartDos.md @@ -0,0 +1,2 @@ +- Use sankey charts sparingly. They are complex and need time and explanation to be understood by the user. +- Aggregate the data to fit into a simpler sankey chart when there are lot of layers involved. diff --git a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartOverview.md b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartOverview.md index b3e549f1f4bf5..ad4d98c0681b0 100644 --- a/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartOverview.md +++ b/packages/react-examples/src/react-charting/SankeyChart/docs/SankeyChartOverview.md @@ -1,8 +1,7 @@ -
-

- A sankey diagram is a visualization used to depict a flow from one set of values to another. The things - being connected are called nodes and the connections are called links. Sankeys are best used when you want - to show a many-to-many mapping between two domains (e.g., universities and majors) or multiple paths - through a set of stages -

-
+A Sankey chart visualizes a flow from one entity to another. Its goal is to clearly show the path of a depicted property. By hovering over a path, the user can highlight the source and destination of flow of this information. + +The height of each column is proportional to the size of data, similar to a pie chart. Sankey also utilizes streams to visualize relationships between different column groups and their associated values. + +Sankey charts are best used to visualize important relationships in a multi-level flow and help to investigate and monitor flow of information within workflows. Eg - Flow of mail data through different ip addresses. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/SparklineChart/SparklineChart.doc.tsx b/packages/react-examples/src/react-charting/SparklineChart/SparklineChart.doc.tsx index 94be88fcffb80..494cb0c0aceb2 100644 --- a/packages/react-examples/src/react-charting/SparklineChart/SparklineChart.doc.tsx +++ b/packages/react-examples/src/react-charting/SparklineChart/SparklineChart.doc.tsx @@ -21,6 +21,8 @@ export const SparklineChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/SparklineChart/SparklineChartPage.tsx b/packages/react-examples/src/react-charting/SparklineChart/SparklineChartPage.tsx index 3a94d40a07dba..d5448666b505c 100644 --- a/packages/react-examples/src/react-charting/SparklineChart/SparklineChartPage.tsx +++ b/packages/react-examples/src/react-charting/SparklineChart/SparklineChartPage.tsx @@ -44,6 +44,16 @@ export class SparklineChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md index 5846efdec791c..d029a5129b42c 100644 --- a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md +++ b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartBestPractices.md @@ -1,3 +1,9 @@ +### Layout + +A standard sparkline component is comprised of a single area chart. The value shown to the right of the sparkline represents the latest data of the trendline. It does not represent the average value of the data plotted. Most scenarios that require sparklines typically need only green and red to show positive or negative trend, respectively. If representing a neutral trend, use `Comm Blue #0078D4`. However, the color of the sparkline can be customized to suit your product and scenario you’re designing for. You can use positive, negative, and neutral colors next to each other. + ### Content -SparklineChart best practices content placeholder. +- **Line** 1px line +- **Fill** Same color as line with opacity of 0.2 +- **Legend** Latest value to show as label after the chart. diff --git a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDonts.md b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDonts.md new file mode 100644 index 0000000000000..b3b8b51a99a32 --- /dev/null +++ b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDonts.md @@ -0,0 +1 @@ +- Don’t enable a hover state. The most important value is displayed directly next to the chart. diff --git a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDos.md b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDos.md new file mode 100644 index 0000000000000..998c1659444a0 --- /dev/null +++ b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartDos.md @@ -0,0 +1,2 @@ +- The most important value is displayed directly next to the chart. +- Sparkline can be embedded within tables, paragraphs, lists and more. diff --git a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartOverview.md b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartOverview.md index 5de1b0f043f5a..2ab3819e44dff 100644 --- a/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartOverview.md +++ b/packages/react-examples/src/react-charting/SparklineChart/docs/SparklineChartOverview.md @@ -1,7 +1,5 @@ -
-

- A sparkline is a very small area chart without axes or coordinates, usually representing trend over time. - When used as a component in lists, the sparkline is paired with a numeric value that summarizes or - provides the most current value of the chart. -

-
+A sparkline is a very small area chart without axes or coordinates. It is useful for quick and high-level evaluation of trends. It can be an effective solution for presenting an overview of multiple series (high cardinality of data) simultaneously while maximizing legibility. + +From Edward Tufte: "A sparkline is a small intense, simple, word-sized graphic with typographic resolution. Sparklines mean that graphics are no longer cartoonish special occasions with captions and boxes, but rather sparkline graphics can be anywhere a word or number is present - embedded in a sentence, table, headline, map, spreadsheet, graphic." + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChart.doc.tsx b/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChart.doc.tsx index bce75ea67e60e..72f707794aca2 100644 --- a/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChart.doc.tsx @@ -61,6 +61,8 @@ export const StackedBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChartPage.tsx b/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChartPage.tsx index 86ccb4d0e7c2a..211638fad80b5 100644 --- a/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/StackedBarChart/StackedBarChartPage.tsx @@ -76,6 +76,16 @@ export class StackedBarChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDonts.md')} + + } isHeaderVisible={this.props.isHeaderVisible} /> ); diff --git a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md index 4c78f6a358b6e..12596c1346d20 100644 --- a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartBestPractices.md @@ -1,3 +1,27 @@ +### Layout + +The stacked bar chart is available in 100% format for actual scale and n/M scale. + +Refer to horizontal bar chart page for common layout guidance. + ### Content -StackedBarChart best practices content placeholder. +The stacked bar chart has legends component to interact with individual categories. + +Refer to horizontal bar chart page for common content guidance. + +### Accessibility + +Refer to horizontal bar chart page for common accessibility guidance. + +### Customizing the chart + +- Single stacked bar chart takes `data` attribute which is of type `IChartDataPoint[]` +- Ratio on top of the chart is shown if it has only two data points. For the rest of cases the ratio is not shown +- A number is displayed on the top of stacked bar chart if it has only one data point. This number shown is the data that is passed to the chart. +- Stacked bar chart supports specifying a target value for the chart. The target shows up as a colored arrow in the chart. It can be set using the `targetData` prop. +- Stacked bar chart also supports specifying a benchmark value for the chart. The benchmark shows up as a colored arrow in the chart. It can be set using the `benchmarkData` prop. +- Ratio and number are not shown if `ignoreFixStyle` is set to true. They are also ignored if `hideNumberDisplay` is set to true. `chartDataAccessibilityData` prop is enabled only if ratio or numbers are enabled to be shown. +- If a datapoint is marked as `placeHolder` there will be no corresponding legend. +- Use `onRenderCalloutPerDataPoint` to customize the hover callout content. +- If `enabledLegendsWrapLines` is set, long legends will be wrapped otherwise legends will be showed as an overflow callout. diff --git a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDonts.md b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDonts.md new file mode 100644 index 0000000000000..0adbceeae28ee --- /dev/null +++ b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDonts.md @@ -0,0 +1,2 @@ +- Avoid having more than 20 bars in the chart. +- The n/M variant should be used only when a value has to be compared against its target value. diff --git a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDos.md b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDos.md new file mode 100644 index 0000000000000..765df0d064657 --- /dev/null +++ b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartDos.md @@ -0,0 +1 @@ +- Use stacked horizontal bar chart if the length of labels is longer. diff --git a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartOverview.md b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartOverview.md index 677564f5b6da6..29dd15db11c10 100644 --- a/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartOverview.md +++ b/packages/react-examples/src/react-charting/StackedBarChart/docs/StackedBarChartOverview.md @@ -1,68 +1,5 @@ -
-

- StackedBarChart shows the data in a bar format. It has two variations: single stacked and multi-stacked. - The stacked bar chart comes with a legends component built in. Below are a few points that will help you - understand the stacked bar chart variants better: -

-

Single stacked bar chart

-
    -
  • Single stacked bar chart takes 'data' attribute which is of type IChartDataPoint[]
    • -
  • - Ratio on top of the chart is shown if it has only two data points. For the rest of cases the ratio is - not shown -
    • -
  • - A number is displayed on the top of stacked bar chart if it has only one data point. This number shown - is the data that is passed to the chart. -
    • -
  • - Stacked bar chart supports specifying a target value for the chart. The target shows up as a colored - arrow in the chart. It can be set using the targetData prop. -
    • -
  • - Stacked bar chart also supports specifying a benchmark value for the chart. The benchmark shows up as a - colored arrow in the chart. It can be set using the benchmarkData prop. -
    • -
  • - Ratio and number are not shown if ignoreFixStyle is set to true. They are also ignored if - hideNumberDisplay is set to true. - chartDataAccessibilityData prop is enabled only if ratio or numbers are enabled to be - shown. -
    • -
  • - If a datapoint is marked as placeHolder there will be no corresponding legend. -
    • -
  • - Use onRenderCalloutPerDataPoint to customize the hover callout content. -
    • -
  • - If enabledLegendsWrapLines is set, long legends will be wrapped otherwise legends will be - showed as an overflow callout -
    • -
-

Multi stacked bar chart

-
    -
  • - Multi-stacked bar chart takes 'data' attribute which is of type IChartDataPoint[][]. It will render the - chart based upon the values given to this attribute. -
    • -
  • - MultiStackedBarChart has an option hideRatio which shows/hides the ratio on top right of - the chart. It is a boolean[], one bool for each bar group. This value is applicable only when there are - 2 datapoints in the chart. Similarly there is an option hideDenominator to hide the - denominator of the ratio if it is enabled. -
    • -
  • - If a datapoint is marked as placeHolder there will be no corresponding legend. The default - color of placeholder data is tertiary grey. -
    • -
  • - If a chart in MultiStackedBarChart shows ratio or number, legends are not displayed for that chart and - vice-versa. -
    • -
  • - A number is displayed on the top of stacked bar chart if it has only one data point. This number shown - is the datapoint that is passed to the chart. -
    • -
-
+Horizontal stacked bar chart displays multiple series of data as stacked bars, with each bar representing a category. The bars are stacked alongside each other, with the length of each bar representing the value of the category of the series. + +The stacked bar chart is a 100% chart. This means the sum of all categories sums up to 100% width of the chart. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/TreeChart/TreeChart.doc.tsx b/packages/react-examples/src/react-charting/TreeChart/TreeChart.doc.tsx index 244ddc39c829a..d38fe2c77a864 100644 --- a/packages/react-examples/src/react-charting/TreeChart/TreeChart.doc.tsx +++ b/packages/react-examples/src/react-charting/TreeChart/TreeChart.doc.tsx @@ -28,6 +28,8 @@ export const TreeChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/TreeChart/TreeChartPage.tsx b/packages/react-examples/src/react-charting/TreeChart/TreeChartPage.tsx index f2e8dc1c925cb..55df72a7e6d34 100644 --- a/packages/react-examples/src/react-charting/TreeChart/TreeChartPage.tsx +++ b/packages/react-examples/src/react-charting/TreeChart/TreeChartPage.tsx @@ -62,6 +62,16 @@ export class TreeChartPage extends React.Component {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/TreeChart/docs/TreeChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md index 9d1fd7e0e7588..dcf343a2f2404 100644 --- a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md +++ b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartBestPractices.md @@ -1,3 +1,42 @@ +### Layout + +The library recommends chart width based on a 12-column layout of the page and suggests using 1 of 4 standardized heights. Product teams must take into account the complexity of the data to decide what size of chart should be used. + +Any interactive node must have a label at the bottom showing the number of children, even if the node is a leaf. This helps in distinguishing between nodes that have further information and ones which do not need to be interacted with. Interactive leaf nodes will have “0 nodes” as their label. + ### Content -TreeChart best practices content placeholder. +- **Parent Node** These are the starting or root node of the tree. This can be an actual node or text labels representing the start of the hierarchy. +- **Branches** Branches are used to connect parent and child nodes. They help the user navigate through the hierarchical flow. +- **Child nodes** Child nodes have parent nodes that supersede them in the hierarchy. We distinguish them in our system as also having further child nodes that branch out. +- **Leaf nodes** Leaf nodes are terminal nodes that have no child connections. + +Each node can contain a heading label followed by a text label or a metric value as demonstrated in the example below. + +### Accessibility + +- The chart can be navigated using tab and arrow keys. On hovering over the node, the node and its parent information is read using a screen reader. +- Use `treeTraversal` to specify the tree traversal order as `preorder` or `levelOrder`. This is used to specify the navigation order of the tree while using keyboard. + +### Customizing the chart + +Tree chart has the following variants. + +#### Two layer chart + +It displays two levels of the tree. Can be used if the space available on the screen is limited. + +The long and compact composition below are applicable for terminal nodes only. + +#### Three layer Long composition + +Consists of three levels of nodes, with nodes stacked one after the other. Specify `composition` as long to enable this variant. + +#### Three layer Compact composition + +Consists of three levels of nodes, with nodes side by side and then stacked one after the other. +Specify `composition` as compact to specify this variant. + +#### Three layer Automatic composition + +When there is space constraint, nodes having more than 2 children are displayed as compact and nodes with less than 2 children are shown in long format. diff --git a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDonts.md b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDonts.md new file mode 100644 index 0000000000000..09cc2661678c0 --- /dev/null +++ b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDonts.md @@ -0,0 +1,3 @@ +- No more than four child or leaf nodes on any given level +- Do not add more than four total levels. +- Narrow widths are not recommended for complex trees unless absolutely necessary. diff --git a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDos.md b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDos.md new file mode 100644 index 0000000000000..3dc6741cf4302 --- /dev/null +++ b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartDos.md @@ -0,0 +1 @@ +- Tree diagrams are meant to flex to your use case. There are some restrictions to ensure the structure supports legibility. Utilize the components to build your tree while staying within these guidelines. diff --git a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartOverview.md b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartOverview.md index e0ba7824bf1b1..bc832806ad00b 100644 --- a/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartOverview.md +++ b/packages/react-examples/src/react-charting/TreeChart/docs/TreeChartOverview.md @@ -1,25 +1,5 @@ -
-

Tree chart component involves two types of layers of tree.

-

Two layer chart

-

- Consists of two levels of tree, and can be navigated using tab and arrow keys, if we hover over the node, - it reads node and its parent information using a screen reader. -

-

Three layer Long composition

-

- Consists of three levels of nodes, with nodes stacked one after the other. Specify{' '} - composition as long to specify the long composition. -

-

Three layer Compact composition

-

Consists of three levels of nodes, with nodes side by side and then stacked one after the other.

-

The long and compact composition are present for only terminal nodes of a tree

- Specify composition as compact to specify the long composition. -

Three layer Automatic composition

-

- When there's constraint on the space, for nodes having more than 2 children it is implemented as compact - and long for nodes with less than 2 children. -

-

- Use treeTraversal to specify the tree traversal order as preOrder or levelOrder -

-
+Also known as org chart, a tree diagram is used to represent hierarchy in a tree-like structure. A tree chart starts with a parent node. Edges, or lines, connect to nodes to represent the relationship between them. Finally, leaf nodes are members that have no child nodes. + +Tree diagrams are best used to show hierarchy and relationship between entities. They don’t require any metrics – the information can be entirely composed of text. They can also be used to visualize decision trees with each node representing the rules and data distribution. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChart.doc.tsx b/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChart.doc.tsx index 3779e4aa360c6..8bf3d9f85ddaf 100644 --- a/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChart.doc.tsx @@ -61,6 +61,8 @@ export const VerticalBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChartPage.tsx b/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChartPage.tsx index 6d0888915d296..ecfa6ac891df9 100644 --- a/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/VerticalBarChart/VerticalBarChartPage.tsx @@ -78,6 +78,16 @@ export class VerticalBarChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md index 1a40567a85490..8fd33b30f12cb 100644 --- a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartBestPractices.md @@ -1,3 +1,28 @@ +### Layout + +The default bar width is 16px. For dense data, it can be as thin as 8px wide. Always consider the visual weight of the bars in relationship to the rest of the app before choosing this type of chart. + +The padding around the bar chart is a default of 8px from the x and y-axis container. This gives enough room for additional content like label values to display properly without overlapping on to the X-axis ticks. A 2:1 spacing is maintained between all the bars in the graph so that space between two bars is always two times the bar width. This helps to ensure that the graph is not overpowering other data visualizations. + +For charts that display monetary values, the dollar symbol should be displayed as part of the total value. Also call out the currency in the chart title to provide additional context. Chart title can be used to communicate currency when the total labels are hidden. + ### Content -VerticalBarChart best practices content placeholder. +- **Bar segment** Bar segments make up a bar chart. Standard size options are: 8px, 16px, and 24px with 16px being the default. +- **Value labels** (Optional - Off by default) with the option to toggle on in case the data visualization needs to communicate label values to users. + +### Accessibility + +Bar graphs should be flexible to their containers. They will change widths to fit their environment. This also means that bar labels will rotate or truncate to best fit the available space in the chart (Auto adjusting labels coming soon). + +Type truncation should happen when the total value exceeds one thousand including 1 decimal place for the hundreds. For example, display full value for 600, 983, or 19.53. Truncate 6,000 to 6.0K, 9,801 to 9.8K, and 100,900 to 100.9K. + +### Customizing the chart + +The chart provides an option to select a color scale based on the range of y values. Similar y values will end up having similar colors. Use the `colors` attribute to define the color scale. + +Use `useSingleColor` to use a single color for all bars. + +Use `lineLegendText` and `lineLegendColor` to specify the text and color for legends of lines in the chart. + +The bar labels are shown by default. Set the `hideLabels` prop to hide them. diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDonts.md b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDonts.md new file mode 100644 index 0000000000000..f92b1a6e4e588 --- /dev/null +++ b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDonts.md @@ -0,0 +1 @@ +- Don't use very long labels in vertical bar chart. Long labels use unnecessary space and make the chart skewed. For long labels use horizontal bar chart with axis. diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDos.md b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDos.md new file mode 100644 index 0000000000000..1944bbb985eab --- /dev/null +++ b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartDos.md @@ -0,0 +1 @@ +- Try to keep the number of bars in the chart between 3 and 20 to maximize readability. diff --git a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartOverview.md b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartOverview.md index 7e54bfc2fc043..529196a5ed856 100644 --- a/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartOverview.md +++ b/packages/react-examples/src/react-charting/VerticalBarChart/docs/VerticalBarChartOverview.md @@ -1,31 +1,3 @@ -
-

- A vertical bar chart is used to show comparisons between categories of data, usually over a period of - time. Categories and time are typically shown along the horizontal axis, while the data values are shown - along the vertical axis. -

-

- The bar widths are proportional to the number of bars and space available within the charting area. The - bar width can be changed using the barWidth property. -

-
-

Implementation details

-

- The current vertical bar charts implementation is in the cartesian coordinate system. The cartesian - coordinate system is represented by Cartesian Chart which serves as the base class for vertical bar charts -

-

- The chart provides an option to select a color scale based on the range of y values. Similar y values will - end up having similar color. Use the colors attribute to define the color scale. -

-

- Use useSingleColor to use a single color for all bars. -

-

- Use lineLegendText and lineLegendColor to specify the text and color for legends of lines in - the chart. -

-

- The bar labels are shown by default. Set the hideLabels prop to hide them. -

-
+A vertical bar chart displays data as a series of vertical bars, with each bar representing a category and the height of the bar representing the value of that category. It is commonly used to show comparisons between categories of one or more data sets, usually over a period of time. Categories are shown on the horizontal axis, while the data values are shown along the vertical axis. They could present data over time or in relationship to a whole. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library. diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChart.doc.tsx b/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChart.doc.tsx index bf4056c9336a5..994ae7bb48d65 100644 --- a/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChart.doc.tsx +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChart.doc.tsx @@ -53,6 +53,8 @@ export const VerticalStackedBarChartPageProps: IDocPageProps = { ], overview: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartOverview.md'), bestPractices: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md'), + dos: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDos.md'), + donts: require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDonts.md'), isHeaderVisible: true, isFeedbackVisible: true, }; diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChartPage.tsx b/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChartPage.tsx index 754924e881ae5..66584f85ea9db 100644 --- a/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChartPage.tsx +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/VerticalStackedBarChartPage.tsx @@ -72,6 +72,16 @@ export class VerticalBarChartPage extends React.Component('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md')} } + dos={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDos.md')} + + } + donts={ + + {require('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDonts.md')} + + } /> ); } diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md index cce0040af9c3f..0018870d2ac96 100644 --- a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartBestPractices.md @@ -1,3 +1,31 @@ +### Layout + +Stacked bar charts are ideal for comparing values across two or more categories. They can easily show multiple categories on the same chart. + +Refer to Vertical Bar Chart page for common layout guidance. + ### Content -VerticalStackedBarChart best practices content placeholder. +Refer to Vertical Bar Chart page for common content guidance. + +### Accessibility + +Refer to Vertical Bar Chart page for common accessibility guidance. + +### Customizing the chart + +Here are some commonly used properties to customize the bar chart. + +`bargapmax` sets the maximum gap between bars in a stack. See the prop for more details. + +`barCornerRadius` sets the corner radius of the bars. + +`barMinimumHeight` provides the minimum height of a bar. Bars below this height will be displayed at this height. + +Use `isCalloutForStack` to configure callout to be at stack level or individual datapoint level. + +Define a custom callout rendered per datapoint using `onRenderCalloutPerDataPoint` and per stack using `onRenderCalloutPerStack` + +Use `onBarClick` handler for callback on click of bars + +The bar labels are shown by default. Set the `hideLabels` prop to hide them. diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDonts.md b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDonts.md new file mode 100644 index 0000000000000..45396ae5c058e --- /dev/null +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDonts.md @@ -0,0 +1 @@ +- Refer to Vertical Bar Chart page for common don'ts. diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDos.md b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDos.md new file mode 100644 index 0000000000000..f5ddf35e0a21e --- /dev/null +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartDos.md @@ -0,0 +1 @@ +- Refer to Vertical Bar Chart page for common dos. diff --git a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartOverview.md b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartOverview.md index b41aab38050a1..e208571927922 100644 --- a/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartOverview.md +++ b/packages/react-examples/src/react-charting/VerticalStackedBarChart/docs/VerticalStackedBarChartOverview.md @@ -1,30 +1,5 @@ -
-

- Vertical stacked bar chart shows comparsions between categories of data, but with the ability to break - down and compare parts of a whole. Each bar in the chart represents a whole, and sections within the bar - represents different parts or categories of that whole -

-

- bargapmax sets the maximum gap between bars in a stack. See the prop for more details. -

-

- barCornerRadius sets the corner radius of the bars -

-

- barMinimumHeight provides the minimum height of a bar. Bars below this height will be - displayed at this height. -

-

- Use isCalloutForStack to configure callout to be at stack level or individual datapoint level -

-

- Define a custom callout rendered per datapoint using onRenderCalloutPerDataPoint and per - stack using onRenderCalloutPerStack -

-

- Use onBarClick handler for callback on click of bars -

-

- The bar labels are shown by default. Set the hideLabels prop to hide them. -

-
+Vertical stacked bar chart displays multiple series of data as stacked bars, with each bar representing a category. The bars are stacked on top of each other, with the height of each bar representing the value of the category of the series. + +Categories and their count are shown on the horizontal axis. + +Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library.