@fluentui/react-charting 5.18.8 → 5.18.10

package/docs/TechnicalDetails.md

@@ -0,0 +1,88 @@
+# Technical details
+
+**Overview**
+
+This document describes different chart components in detail.
+
+This can be used as a guide to use the charts and contribute new functionalities or improvements to the library.
+
+**Components**
+
+The charting components are built using following building blocks.
+
+- Cartesian Charts.
+
+  - Charts built using cartesian coordinate system (two axes - x axis perpendicular to y axis) are called cartesian charts. Majority of the chart in the library are cartesian charts. Some charts like horizontal chart, donut chart, sankey and tree charts are non cartesian charts.
+
+- Legends.
+
+  - A legend contains a list of the variables appearing in the chart and an example of their appearance. This information allows the data from each variable to be identified in the chart.
+
+- Hover Callouts.
+
+  - Whenever the mouse is hovered over a datapoint, a callout is shown representing the details of data for that point. For a stacked chart, the hover callout can represent the data for all the points for the same X coordinate.
+
+- Axes.
+
+  - Our charts currently support cartesian axes. Different charts support different type of axes - numerical axis, date or time series axis, string or categorical axis. Detals about supported axes can be found in readme for each chart.
+
+  - Axes support for different charts
+
+    | Chart                      | Numeric Axis | Date Axis | String Axis |
+    | -------------------------- | ------------ | --------- | ----------- |
+    | Line Chart                 | Yes          | Yes       | No          |
+    | Area Chart                 | Yes          | Yes       | No          |
+    | Vertical Bar Chart         | Yes          | No        | Yes         |
+    | Vertical Stacked Bar Chart | Yes          | No        | Yes         |
+    | Grouped Vertical Bar Chart | No           | No        | Yes         |
+    | Heatmap Chart              | Yes          | Yes       | Yes         |
+    | Horizontal Bar Chart       | --           | --        | --          |
+    | Donut Chart                | --           | --        | --          |
+    | Sankey Chart               | --           | --        | --          |
+    | Tree Chart                 | --           | --        | --          |
+    | Sparkline Chart            | --           | --        | --          |
+
+  - 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](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 format 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.
+
+  - Date axis formatting
+    The date axis can be custom formatted using the customDateTimeFormatter prop.
+
+- Event annotations (Available in line charts).
+
+  - Data can be annotated using vertical lines representing the events of interest. See [line chart with events](https://fluentuipr.z22.web.core.windows.net/heads/master/react-charting/demo/index.html#/examples/linechart#Variants) for example.
+
+- Typography.
+
+  - Our font classes represent the type ramp for the fluent design language. Each base class sets a default size, weight, and color.
+
+- Colors
+
+  - The charts are designed using the accessible color palette defined for the fluent design system.
+    Refer [this](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/docs/colors.md) guide for details about charting color palette and its usage.
+
+- Themes
+
+  - The library supports light and dark mode out of box. In addition, consumers can define their own themese as detailed [here](https://github.com/microsoft/fluentui/wiki/Theming)
+
+- Accessibility.
+
+  - Our charts have elaborate accessibility support. The charts are WCAG 2.1 MAS C compliant for accessibility.
+    Consumers can define their own aria labels for each point by setting the `xAxisCalloutAccessibilityData` and `callOutAccessibilityData` properties.
+
+- RTL Support
+
+  - The charts support RTL languages wherever applicable.
+
+- Component Styling
+
+  - [This article](https://github.com/microsoft/fluentui/wiki/Component-Styling) talks about the styling approach followed within charting library.
+
+- Details about ticks.
+  - Tick values are applicable only for date axis. Doesn't work for string or numeric axis.
+    Tickcount works for numeric and date axis. Doesn't work for string (scaleBand) axis.

package/etc/react-charting.api.md

@@ -27,7 +27,7 @@ import { SVGProps } from 'react';
 // @public
 export const AreaChart: React_2.FunctionComponent<IAreaChartProps>;
 
-// @public (undocumented)
+// @public
 export const CartesianChart: React_2.FunctionComponent<IModifiedCartesianChartProps>;
 
 // @public
@@ -151,11 +151,11 @@ export interface IAreaChartProps extends ICartesianChartProps {
     styles?: IStyleFunctionOrObject<ICartesianChartStyleProps, ICartesianChartStyles>;
 }
 
-// @public (undocumented)
+// @public
 export interface IAreaChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface IAreaChartStyles extends ICartesianChartStyles {
 }
 
@@ -205,7 +205,7 @@ export interface IBasestate {
     }[];
 }
 
-// @public (undocumented)
+// @public
 export interface ICartesianChartProps {
     calloutProps?: Partial<ICalloutProps>;
     // @deprecated
@@ -257,7 +257,7 @@ export interface ICartesianChartProps {
     yMinValue?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ICartesianChartStyleProps {
     className?: string;
     color?: string;
@@ -271,7 +271,7 @@ export interface ICartesianChartStyleProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ICartesianChartStyles {
     axisTitle?: IStyle;
     calloutBlockContainer?: IStyle;
@@ -439,11 +439,11 @@ export interface IDonutChartProps extends ICartesianChartProps {
     valueInsideDonut?: string | number;
 }
 
-// @public (undocumented)
+// @public
 export interface IDonutChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface IDonutChartStyles {
     chart?: IStyle;
     legendContainer: IStyle;
@@ -499,7 +499,7 @@ export interface IGaugeChartSegment {
     size: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IGaugeChartStyleProps {
     chartHeight?: number;
     chartValueSize?: number;
@@ -510,7 +510,7 @@ export interface IGaugeChartStyleProps {
     toDrawShape?: boolean;
 }
 
-// @public (undocumented)
+// @public
 export interface IGaugeChartStyles {
     calloutBlockContainer?: IStyle;
     calloutContentRoot?: IStyle;
@@ -561,11 +561,11 @@ export interface IGroupedVerticalBarChartProps extends ICartesianChartProps {
     styles?: IStyleFunctionOrObject<IGroupedVerticalBarChartStyleProps, IGroupedVerticalBarChartStyles>;
 }
 
-// @public (undocumented)
+// @public
 export interface IGroupedVerticalBarChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface IGroupedVerticalBarChartStyles extends ICartesianChartStyles {
     barLabel: IStyle;
     opacityChangeOnHover: IStyle;
@@ -638,11 +638,11 @@ export interface IHeatMapChartProps extends Pick<ICartesianChartProps, Exclude<k
     yAxisStringFormatter?: (point: string) => string;
 }
 
-// @public (undocumented)
+// @public
 export interface IHeatMapChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface IHeatMapChartStyles {
     // (undocumented)
     root?: IStyle;
@@ -674,7 +674,7 @@ export interface IHorizontalBarChartProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IHorizontalBarChartStyleProps {
     barHeight?: number;
     className?: string;
@@ -686,7 +686,7 @@ export interface IHorizontalBarChartStyleProps {
     width: number | undefined;
 }
 
-// @public (undocumented)
+// @public
 export interface IHorizontalBarChartStyles {
     barLabel: IStyle;
     barWrapper: IStyle;
@@ -729,12 +729,12 @@ export interface IHorizontalBarChartWithAxisProps extends ICartesianChartProps {
     yAxisPadding?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IHorizontalBarChartWithAxisStyleProps extends ICartesianChartStyleProps {
     legendColor?: string;
 }
 
-// @public (undocumented)
+// @public
 export interface IHorizontalBarChartWithAxisStyles extends ICartesianChartStyles {
     chartLabel?: IStyle;
     opacityChangeOnHover: IStyle;
@@ -773,7 +773,7 @@ export interface ILegendDataItem {
     legendText: string | number;
 }
 
-// @public
+// @public (undocumented)
 export interface ILegendOverflowData {
     // (undocumented)
     overflow?: ILegend[];
@@ -781,7 +781,7 @@ export interface ILegendOverflowData {
     primary: ILegend[];
 }
 
-// @public (undocumented)
+// @public
 export interface ILegendsProps {
     allowFocusOnLegends?: boolean;
     canSelectMultipleLegends?: boolean;
@@ -812,7 +812,7 @@ export interface ILegendsStyles {
     triangle: IStyle;
 }
 
-// @public (undocumented)
+// @public
 export interface ILegendStyleProps {
     // (undocumented)
     borderColor?: string;
@@ -832,7 +832,7 @@ export interface ILegendStyleProps {
     theme?: ITheme;
 }
 
-// @public
+// @public (undocumented)
 export interface ILegendSubComponentStyles {
     // (undocumented)
     hoverCardStyles: IStyleFunctionOrObject<IHoverCardStyleProps, IHoverCardStyles>;
@@ -899,11 +899,11 @@ export interface ILineChartProps extends ICartesianChartProps {
     styles?: IStyleFunctionOrObject<ILineChartStyleProps, ILineChartStyles>;
 }
 
-// @public (undocumented)
+// @public
 export interface ILineChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface ILineChartStyles extends ICartesianChartStyles {
 }
 
@@ -1015,7 +1015,7 @@ export interface IMultiStackedBarChartProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IMultiStackedBarChartStyleProps {
     barHeight?: number;
     className?: string;
@@ -1028,7 +1028,7 @@ export interface IMultiStackedBarChartStyleProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IMultiStackedBarChartStyles {
     barLabel: IStyle;
     chart: IStyle;
@@ -1064,10 +1064,10 @@ export interface IPieChartProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export type IPieChartStyleProps = Required<Pick<IPieChartProps, 'theme' | 'width' | 'height'>> & Pick<IPieChartProps, 'className'>;
 
-// @public (undocumented)
+// @public
 export interface IPieChartStyles {
     chart?: IStyle;
     chartTitle?: IStyle;
@@ -1105,7 +1105,7 @@ export interface ISankeyChartProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ISankeyChartStyleProps {
     // (undocumented)
     className?: string;
@@ -1119,7 +1119,7 @@ export interface ISankeyChartStyleProps {
     width: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ISankeyChartStyles {
     calloutContentRoot?: IStyle;
     links?: IStyle;
@@ -1158,7 +1158,7 @@ export interface ISparklineProps {
 export interface ISparklineStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface ISparklineStyles {
     // (undocumented)
     inlineBlock?: IStyle;
@@ -1197,7 +1197,7 @@ export interface IStackedBarChartProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IStackedBarChartStyleProps {
     barHeight?: number;
     benchmarkColor?: string;
@@ -1214,7 +1214,7 @@ export interface IStackedBarChartStyleProps {
     width?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IStackedBarChartStyles {
     benchmark: IStyle;
     benchmarkContainer: IStyle;
@@ -1229,7 +1229,7 @@ export interface IStackedBarChartStyles {
     target: IStyle;
 }
 
-// @public
+// @public (undocumented)
 export interface ITreeChartDataPoint {
     bodytext?: string;
     children?: Array<ITreeChartDataPoint>;
@@ -1253,7 +1253,7 @@ export interface ITreeDataStructure {
     y: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ITreeProps {
     className?: string;
     composition?: NodesComposition.long | NodesComposition.compact;
@@ -1274,13 +1274,13 @@ export interface ITreeState {
     _width: number;
 }
 
-// @public (undocumented)
+// @public
 export interface ITreeStyleProps {
     className?: string;
     theme: ITheme;
 }
 
-// @public (undocumented)
+// @public
 export interface ITreeStyles {
     link: IStyle;
     rectBodyText: IStyle;
@@ -1321,12 +1321,12 @@ export interface IVerticalBarChartProps extends ICartesianChartProps {
     xAxisPadding?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface IVerticalBarChartStyleProps extends ICartesianChartStyleProps {
     legendColor?: string;
 }
 
-// @public (undocumented)
+// @public
 export interface IVerticalBarChartStyles extends ICartesianChartStyles {
     barLabel: IStyle;
     // @deprecated
@@ -1370,11 +1370,11 @@ export interface IVerticalStackedBarChartProps extends ICartesianChartProps {
     yMinValue?: undefined;
 }
 
-// @public (undocumented)
+// @public
 export interface IVerticalStackedBarChartStyleProps extends ICartesianChartStyleProps {
 }
 
-// @public (undocumented)
+// @public
 export interface IVerticalStackedBarChartStyles extends ICartesianChartStyles {
     barLabel: IStyle;
     // @deprecated

package/lib/components/AreaChart/AreaChart.types.d.ts

@@ -3,7 +3,7 @@ import { IChartProps, IRefArrayData, IBasestate, ILineChartDataPoint, ILineChart
 import { ICartesianChartStyles, ICartesianChartStyleProps, ICartesianChartProps, IChildProps } from '../CommonComponents/CartesianChart.types';
 export type { IChildProps, IRefArrayData, IBasestate, ILineChartDataPoint, ILineChartPoints, IMargins };
 /**
- * IAreaChartProps properties for area chart.
+ * Area Chart properties.
  * {@docCategory AreaChart}
  */
 export interface IAreaChartProps extends ICartesianChartProps {
@@ -40,7 +40,15 @@ export interface IAreaChartProps extends ICartesianChartProps {
     enablePerfOptimization?: boolean;
     optimizeLargeData?: boolean;
 }
+/**
+ * Area Chart styles
+ * {@docCategory AreaChart}
+ */
 export interface IAreaChartStyles extends ICartesianChartStyles {
 }
+/**
+ * Area Chart style properties
+ * {@docCategory AreaChart}
+ */
 export interface IAreaChartStyleProps extends ICartesianChartStyleProps {
 }

package/lib/components/AreaChart/AreaChart.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"AreaChart.types.js","sourceRoot":"../src/","sources":["components/AreaChart/AreaChart.types.ts"],"names":[],"mappings":"","sourcesContent":["import { IRenderFunction, IStyleFunctionOrObject } from '@fluentui/react/lib/Utilities';\nimport {\n  IChartProps,\n  IRefArrayData,\n  IBasestate,\n  ILineChartDataPoint,\n  ILineChartPoints,\n  ICustomizedCalloutData,\n  IMargins,\n} from '../../types/index';\nimport {\n  ICartesianChartStyles,\n  ICartesianChartStyleProps,\n  ICartesianChartProps,\n  IChildProps,\n} from '../CommonComponents/CartesianChart.types';\n\nexport type { IChildProps, IRefArrayData, IBasestate, ILineChartDataPoint, ILineChartPoints, IMargins };\n\n/**\n * IAreaChartProps properties for area chart.\n * {@docCategory AreaChart}\n */\nexport interface IAreaChartProps extends ICartesianChartProps {\n  /**\n   * Data to render in the chart.\n   */\n  data: IChartProps;\n\n  /**\n   * This prop is used to draw Y axis grid lines on the chart. Default value will be false\n   * @deprecated now lines are shown by default\n   * no need to use this prop\n   */\n  showYAxisGridLines?: boolean;\n\n  /**\n   * Call to provide customized styling that will layer on top of the variant rules.\n   */\n  styles?: IStyleFunctionOrObject<ICartesianChartStyleProps, ICartesianChartStyles>;\n\n  /**\n   * Define a custom callout renderer for a data point\n   */\n  onRenderCalloutPerDataPoint?: IRenderFunction<ICustomizedCalloutData>;\n\n  /**\n   * Define a custom callout renderer for a stack; default is to render per data point\n   */\n  onRenderCalloutPerStack?: IRenderFunction<ICustomizedCalloutData>;\n\n  /**\n   * The prop used to define the culture to localized the numbers\n   */\n  culture?: string;\n\n  /**\n   * @default false\n   * The prop used to enable the perf optimization\n   */\n  enablePerfOptimization?: boolean;\n\n  /*\n   * Optimize area chart rendering for large data set.\n   */\n  optimizeLargeData?: boolean;\n}\n\nexport interface IAreaChartStyles extends ICartesianChartStyles {}\n\nexport interface IAreaChartStyleProps extends ICartesianChartStyleProps {}\n"]}
+{"version":3,"file":"AreaChart.types.js","sourceRoot":"../src/","sources":["components/AreaChart/AreaChart.types.ts"],"names":[],"mappings":"","sourcesContent":["import { IRenderFunction, IStyleFunctionOrObject } from '@fluentui/react/lib/Utilities';\nimport {\n  IChartProps,\n  IRefArrayData,\n  IBasestate,\n  ILineChartDataPoint,\n  ILineChartPoints,\n  ICustomizedCalloutData,\n  IMargins,\n} from '../../types/index';\nimport {\n  ICartesianChartStyles,\n  ICartesianChartStyleProps,\n  ICartesianChartProps,\n  IChildProps,\n} from '../CommonComponents/CartesianChart.types';\n\nexport type { IChildProps, IRefArrayData, IBasestate, ILineChartDataPoint, ILineChartPoints, IMargins };\n\n/**\n * Area Chart properties.\n * {@docCategory AreaChart}\n */\nexport interface IAreaChartProps extends ICartesianChartProps {\n  /**\n   * Data to render in the chart.\n   */\n  data: IChartProps;\n\n  /**\n   * This prop is used to draw Y axis grid lines on the chart. Default value will be false\n   * @deprecated now lines are shown by default\n   * no need to use this prop\n   */\n  showYAxisGridLines?: boolean;\n\n  /**\n   * Call to provide customized styling that will layer on top of the variant rules.\n   */\n  styles?: IStyleFunctionOrObject<ICartesianChartStyleProps, ICartesianChartStyles>;\n\n  /**\n   * Define a custom callout renderer for a data point\n   */\n  onRenderCalloutPerDataPoint?: IRenderFunction<ICustomizedCalloutData>;\n\n  /**\n   * Define a custom callout renderer for a stack; default is to render per data point\n   */\n  onRenderCalloutPerStack?: IRenderFunction<ICustomizedCalloutData>;\n\n  /**\n   * The prop used to define the culture to localized the numbers\n   */\n  culture?: string;\n\n  /**\n   * @default false\n   * The prop used to enable the perf optimization\n   */\n  enablePerfOptimization?: boolean;\n\n  /*\n   * Optimize area chart rendering for large data set.\n   */\n  optimizeLargeData?: boolean;\n}\n\n/**\n * Area Chart styles\n * {@docCategory AreaChart}\n */\nexport interface IAreaChartStyles extends ICartesianChartStyles {}\n\n/**\n * Area Chart style properties\n * {@docCategory AreaChart}\n */\nexport interface IAreaChartStyleProps extends ICartesianChartStyleProps {}\n"]}

package/lib/components/CommonComponents/CartesianChart.base.js

@@ -473,6 +473,7 @@ var CartesianChartBase = /** @class */ (function (_super) {
         return false;
     };
     CartesianChartBase.prototype._getCalloutContent = function (xValue, index, yValueHoverSubCountsExists, isLast) {
+        var _a;
         var marginStyle = isLast ? {} : { marginRight: '16px' };
         var toDrawShape = xValue.index !== undefined && xValue.index !== -1;
         var _classNames = getClassNames(this.props.styles, {
@@ -501,7 +502,7 @@ var CartesianChartBase = /** @class */ (function (_super) {
                         React.createElement("div", { className: _classNames.calloutlegendText },
                             " ",
                             xValue.legend),
-                        React.createElement("div", { className: _classNames.calloutContentY }, convertToLocaleString(xValue.yAxisCalloutData ? xValue.yAxisCalloutData : xValue.y || xValue.data, culture))))));
+                        React.createElement("div", { className: _classNames.calloutContentY }, convertToLocaleString(xValue.yAxisCalloutData ? xValue.yAxisCalloutData : (_a = xValue.y) !== null && _a !== void 0 ? _a : xValue.data, culture))))));
         }
         else {
             var subcounts_1 = xValue.yAxisCalloutData;