@fluentui/react-charts 0.0.0-nightly-20250603-0406.1 → 0.0.0-nightly-20250604-0406.1

package/lib/utilities/utilities.js

@@ -8,6 +8,7 @@ import { timeSecond as d3TimeSecond, timeMinute as d3TimeMinute, timeHour as d3T
 import { curveLinear as d3CurveLinear, curveNatural as d3CurveNatural, curveStep as d3CurveStep, curveStepAfter as d3CurveStepAfter, curveStepBefore as d3CurveStepBefore } from 'd3-shape';
 import { formatPrefix as d3FormatPrefix } from 'd3-format';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
+import { formatDateToLocaleString, formatToLocaleString, getMultiLevelDateTimeFormatOptions } from '@fluentui/chart-utilities';
 export var ChartTypes;
 (function(ChartTypes) {
     ChartTypes[ChartTypes["AreaChart"] = 0] = "AreaChart";
@@ -31,6 +32,30 @@ export var YAxisType;
     YAxisType[YAxisType["DateAxis"] = 1] = "DateAxis";
     YAxisType[YAxisType["StringAxis"] = 2] = "StringAxis";
 })(YAxisType || (YAxisType = {}));
+function yAxisTickFormatterInternal(value, limitWidth = false) {
+    // Use SI format prefix with 2 decimal places without insignificant trailing zeros
+    let formatter = d3FormatPrefix('.2~', value);
+    if (Math.abs(value) < 1) {
+        // Don't use SI notation for small numbers as it is less readable
+        formatter = d3Format('.2~g');
+    } else if (limitWidth && Math.abs(value) >= 1000) {
+        // If width is limited, use SI format prefix with 1 point precision
+        formatter = d3FormatPrefix('.1~', value);
+    }
+    const formattedValue = formatter(value);
+    // Replace 'G' with 'B' if the value is greater than 10^9 as it is a more common convention
+    if (Math.abs(value) >= 1e9) {
+        return formattedValue.replace('G', 'B');
+    }
+    return formattedValue;
+}
+/**
+ * Formatter for y axis ticks.
+ * @param value - The number to format.
+ * @returns The formatted string .
+ */ export function defaultYAxisTickFormatter(value) {
+    return yAxisTickFormatterInternal(value);
+}
 /**
  * Create Numeric X axis
  * @export
@@ -51,7 +76,7 @@ export var YAxisType;
             return d3Format(tickParams.tickFormat)(domainValue);
         }
         const xAxisValue = typeof domainValue === 'number' ? domainValue : domainValue.valueOf();
-        return convertToLocaleString(xAxisValue, culture);
+        return formatToLocaleString(xAxisValue, culture);
     };
     if (hideTickOverlap && typeof xAxisCount === 'undefined') {
         const longestLabelWidth = calculateLongestLabelWidth(xAxisScale.ticks().map(tickFormat), '.fui-cart__xAxis text') + 20;
@@ -75,16 +100,145 @@ export var YAxisType;
         tickValues
     };
 }
-function multiFormat(date, locale, useUTC) {
+/**
+ * This function returns a multilevel formatter for a given date range.
+ * It determines the appropriate date format to accommodate each tick value.
+ * The goal is to represent the date label in the smallest possible format without loss of information.
+ * The challenge here is to adhere to locale specific formats while ensuring the complete label is shown.
+ * There is an exhaustive map of all possible date/time units and their respective formats.
+ * Based on the range of formatting granularity levels, a format spanning the range is returned.
+ * @param startLevel - The starting level of the date format.
+ * @param endLevel - The ending level of the date format.
+ * @param locale - The locale object for formatting.
+ * @param useUTC
+ * @returns
+ */ function getMultiLevelD3DateFormatter(startLevel, endLevel, locale, useUTC) {
     const timeFormat = locale ? useUTC ? locale.utcFormat : locale.format : useUTC ? d3UtcFormat : d3TimeFormat;
-    const formatMillisecond = timeFormat('.%L');
-    const formatSecond = timeFormat(':%S');
-    const formatMinute = timeFormat('%I:%M');
-    const formatHour = timeFormat('%I %p');
-    const formatDay = timeFormat('%a %d');
-    const formatWeek = timeFormat('%b %d');
-    const formatMonth = timeFormat('%B');
-    const formatYear = timeFormat('%Y');
+    // Refer to https://d3js.org/d3-time-format#locale_format to see explanation about each format specifier
+    const DEFAULT = '%c';
+    const MS = '.%L';
+    const MS_S = ':%S.%L';
+    const MS_S_MIN = '%M:%S.%L';
+    const MS_S_MIN_H = '%-I:%M:%S.%L %p';
+    const MS_S_MIN_H_D = '%a %d, %X';
+    const MS_S_MIN_H_D_W = '%b %d, %X';
+    const MS_S_MIN_H_D_W_M = MS_S_MIN_H_D_W;
+    const MS_S_MIN_H_D_W_M_Y = DEFAULT;
+    const S = ':%S';
+    const S_MIN = '%-I:%M:%S';
+    const S_MIN_H = '%X';
+    const S_MIN_H_D = MS_S_MIN_H_D;
+    const S_MIN_H_D_W = MS_S_MIN_H_D_W;
+    const S_MIN_H_D_W_M = MS_S_MIN_H_D_W_M;
+    const S_MIN_H_D_W_M_Y = DEFAULT;
+    const MIN = '%-I:%M %p';
+    const MIN_H = MIN;
+    const MIN_H_D = '%a %d, %-I:%M %p';
+    const MIN_H_D_W = '%b %d, %-I:%M %p';
+    const MIN_H_D_W_M = MIN_H_D_W;
+    const MIN_H_D_W_M_Y = '%x, %-I:%M %p';
+    const H = '%-I %p';
+    const H_D = '%a %d, %-I %p';
+    const H_D_W = '%b %d, %-I %p';
+    const H_D_W_M = H_D_W;
+    const H_D_W_M_Y = '%x, %-I %p';
+    const D = '%a %d';
+    const D_W = '%b %d';
+    const D_W_M = D_W;
+    const D_W_M_Y = '%x';
+    const W = D_W;
+    const W_M = W;
+    const W_M_Y = D_W_M_Y;
+    const M = '%B';
+    const M_Y = '%b %Y';
+    const Y = '%Y';
+    const MULTI_LEVEL_DATE_TIME_FORMATS = [
+        // ms, s, min, h, d, w, m, y
+        [
+            MS,
+            MS_S,
+            MS_S_MIN,
+            MS_S_MIN_H,
+            MS_S_MIN_H_D,
+            MS_S_MIN_H_D_W,
+            MS_S_MIN_H_D_W_M,
+            MS_S_MIN_H_D_W_M_Y
+        ],
+        [
+            DEFAULT,
+            S,
+            S_MIN,
+            S_MIN_H,
+            S_MIN_H_D,
+            S_MIN_H_D_W,
+            S_MIN_H_D_W_M,
+            S_MIN_H_D_W_M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            MIN,
+            MIN_H,
+            MIN_H_D,
+            MIN_H_D_W,
+            MIN_H_D_W_M,
+            MIN_H_D_W_M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            H,
+            H_D,
+            H_D_W,
+            H_D_W_M,
+            H_D_W_M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            D,
+            D_W,
+            D_W_M,
+            D_W_M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            W,
+            W_M,
+            W_M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            M,
+            M_Y
+        ],
+        [
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            DEFAULT,
+            Y
+        ]
+    ];
+    const formatter = timeFormat(MULTI_LEVEL_DATE_TIME_FORMATS[startLevel][endLevel]);
+    return formatter;
+}
+function getDateFormatLevel(date, useUTC) {
     const timeSecond = useUTC ? d3UtcSecond : d3TimeSecond;
     const timeMinute = useUTC ? d3UtcMinute : d3TimeMinute;
     const timeHour = useUTC ? d3UtcHour : d3TimeHour;
@@ -92,7 +246,43 @@ function multiFormat(date, locale, useUTC) {
     const timeMonth = useUTC ? d3UtcMonth : d3TimeMonth;
     const timeWeek = useUTC ? d3UtcWeek : d3TimeWeek;
     const timeYear = useUTC ? d3UtcYear : d3TimeYear;
-    return (timeSecond(date) < date ? formatMillisecond : timeMinute(date) < date ? formatSecond : timeHour(date) < date ? formatMinute : timeDay(date) < date ? formatHour : timeMonth(date) < date ? timeWeek(date) < date ? formatDay : formatWeek : timeYear(date) < date ? formatMonth : formatYear)(date);
+    const formats = [
+        {
+            formatLevel: 0,
+            condition: (d)=>timeSecond(d) < d
+        },
+        {
+            formatLevel: 1,
+            condition: (d)=>timeMinute(d) < d
+        },
+        {
+            formatLevel: 2,
+            condition: (d)=>timeHour(d) < d
+        },
+        {
+            formatLevel: 3,
+            condition: (d)=>timeDay(d) < d
+        },
+        {
+            formatLevel: 4,
+            condition: (d)=>timeMonth(d) < d && timeWeek(d) < d
+        },
+        {
+            formatLevel: 5,
+            condition: (d)=>timeMonth(d) < d
+        },
+        {
+            formatLevel: 6,
+            condition: (d)=>timeYear(d) < d
+        },
+        {
+            formatLevel: 7,
+            condition: ()=>true
+        }
+    ];
+    const matchedFormat = formats.find(({ condition })=>condition(date));
+    var _matchedFormat_formatLevel;
+    return (_matchedFormat_formatLevel = matchedFormat === null || matchedFormat === void 0 ? void 0 : matchedFormat.formatLevel) !== null && _matchedFormat_formatLevel !== void 0 ? _matchedFormat_formatLevel : 7;
 }
 /**
  * Creating Date x axis of the Chart
@@ -100,26 +290,37 @@ function multiFormat(date, locale, useUTC) {
  * @param {IXAxisParams} xAxisParams
  * @param {ITickParams} tickParams
  */ export function createDateXAxis(xAxisParams, tickParams, culture, options, timeFormatLocale, customDateTimeFormatter, useUTC) {
-    const { domainNRangeValues, xAxisElement, tickPadding = 6, xAxistickSize = 6, xAxisCount, hideTickOverlap } = xAxisParams;
-    const xAxisScale = useUTC ? d3ScaleUtc() : d3ScaleTime();
+    const { domainNRangeValues, xAxisElement, tickPadding = 6, xAxistickSize = 6, xAxisCount } = xAxisParams;
+    const isUtcSet = useUTC === true || useUTC === 'utc';
+    const xAxisScale = isUtcSet ? d3ScaleUtc() : d3ScaleTime();
     xAxisScale.domain([
         domainNRangeValues.dStartValue,
         domainNRangeValues.dEndValue
     ]).range([
         domainNRangeValues.rStartValue,
         domainNRangeValues.rEndValue
-    ]);
+    ]).nice();
     let tickCount = xAxisCount !== null && xAxisCount !== void 0 ? xAxisCount : 6;
+    let lowestFormatLevel = 100;
+    let highestFormatLevel = -1;
+    const locale = timeFormatLocale ? d3TimeFormatLocale(timeFormatLocale) : undefined;
+    xAxisScale.ticks().forEach((domainValue)=>{
+        const formatLevel = getDateFormatLevel(domainValue, isUtcSet);
+        if (formatLevel > highestFormatLevel) {
+            highestFormatLevel = formatLevel;
+        }
+        if (formatLevel < lowestFormatLevel) {
+            lowestFormatLevel = formatLevel;
+        }
+    });
+    const formatOptions = options !== null && options !== void 0 ? options : getMultiLevelDateTimeFormatOptions(lowestFormatLevel, highestFormatLevel);
+    const formatFn = getMultiLevelD3DateFormatter(lowestFormatLevel, highestFormatLevel, locale, isUtcSet);
     const tickFormat = (domainValue, _index)=>{
         if (customDateTimeFormatter) {
             return customDateTimeFormatter(domainValue);
         }
-        if (culture && options) {
-            return domainValue.toLocaleString(culture, options);
-        }
         if (timeFormatLocale) {
-            const locale = d3TimeFormatLocale(timeFormatLocale);
-            return multiFormat(domainValue, locale, useUTC);
+            return formatFn(domainValue);
         }
         if (culture === undefined && tickParams.tickFormat) {
             if (useUTC) {
@@ -128,13 +329,12 @@ function multiFormat(date, locale, useUTC) {
                 return d3TimeFormat(tickParams.tickFormat)(domainValue);
             }
         }
-        return multiFormat(domainValue, undefined, useUTC);
+        return formatDateToLocaleString(domainValue, culture, useUTC ? true : false, false, formatOptions);
     };
-    if (hideTickOverlap && typeof xAxisCount === 'undefined') {
-        const longestLabelWidth = calculateLongestLabelWidth(xAxisScale.ticks().map(tickFormat), '.fui-cart__xAxis text') + 40;
-        const [start, end] = xAxisScale.range();
-        tickCount = Math.max(1, Math.floor(Math.abs(end - start) / longestLabelWidth));
-    }
+    const longestLabelWidth = calculateLongestLabelWidth(xAxisScale.ticks().map(tickFormat), '.fui-cart__xAxis text') + 40;
+    const [start, end] = xAxisScale.range();
+    const maxPossibleTickCount = Math.max(1, Math.floor(Math.abs(end - start) / longestLabelWidth));
+    tickCount = Math.min(maxPossibleTickCount, xAxisCount !== null && xAxisCount !== void 0 ? xAxisCount : tickCount);
     const xAxis = d3AxisBottom(xAxisScale).tickSize(xAxistickSize).tickPadding(tickPadding).ticks(tickCount).tickFormat(tickFormat);
     tickParams.tickValues ? xAxis.tickValues(tickParams.tickValues) : '';
     if (xAxisElement) {
@@ -164,7 +364,7 @@ function multiFormat(date, locale, useUTC) {
     var _tickParams_tickValues;
     let tickValues = (_tickParams_tickValues = tickParams.tickValues) !== null && _tickParams_tickValues !== void 0 ? _tickParams_tickValues : dataset;
     const tickFormat = (domainValue, _index)=>{
-        return convertToLocaleString(domainValue, culture);
+        return formatToLocaleString(domainValue, culture);
     };
     if (hideTickOverlap) {
         let nonOverlappingTickValues = [];
@@ -279,7 +479,7 @@ function handleFloatingPointPrecisionError(num) {
         case 6:
             return createYAxisForHorizontalBarChartWithAxis(yAxisParams, isRtl, axisData, barWidth);
         default:
-            return createYAxisForOtherCharts(yAxisParams, isRtl, axisData, isIntegralDataset, chartType, useSecondaryYScale, roundedTicks);
+            return createNumericYAxisForOtherCharts(yAxisParams, isRtl, axisData, isIntegralDataset, chartType, useSecondaryYScale, roundedTicks);
     }
 }
 export function createYAxisForHorizontalBarChartWithAxis(yAxisParams, isRtl, axisData, barWidth) {
@@ -300,11 +500,11 @@ export function createYAxisForHorizontalBarChartWithAxis(yAxisParams, isRtl, axi
     ]);
     const axis = isRtl ? d3AxisRight(yAxisScale) : d3AxisLeft(yAxisScale);
     const yAxis = axis.tickPadding(tickPadding).ticks(yAxisTickCount);
-    yAxisTickFormat ? yAxis.tickFormat(yAxisTickFormat) : yAxis.tickFormat(d3Format('.2~s'));
+    yAxisTickFormat ? yAxis.tickFormat(yAxisTickFormat) : yAxis.tickFormat(defaultYAxisTickFormatter);
     yAxisElement ? d3Select(yAxisElement).call(yAxis).selectAll('text').attr('aria-hidden', 'true') : '';
     return yAxisScale;
 }
-export function createYAxisForOtherCharts(yAxisParams, isRtl, axisData, isIntegralDataset, chartType, useSecondaryYScale = false, roundedTicks = false) {
+export function createNumericYAxisForOtherCharts(yAxisParams, isRtl, axisData, isIntegralDataset, chartType, useSecondaryYScale = false, roundedTicks = false) {
     const { yMinMaxValues = {
         startValue: 0,
         endValue: 0
@@ -330,7 +530,7 @@ export function createYAxisForOtherCharts(yAxisParams, isRtl, axisData, isIntegr
     ]);
     const axis = !isRtl && useSecondaryYScale || isRtl && !useSecondaryYScale ? d3AxisRight(yAxisScale) : d3AxisLeft(yAxisScale);
     const yAxis = axis.tickPadding(tickPadding).tickValues(domainValues).tickSizeInner(-(containerWidth - margins.left - margins.right));
-    yAxisTickFormat ? yAxis.tickFormat(yAxisTickFormat) : yAxis.tickFormat(d3Format('.2~s'));
+    yAxisTickFormat ? yAxis.tickFormat(yAxisTickFormat) : yAxis.tickFormat(defaultYAxisTickFormatter);
     yAxisElement ? d3Select(yAxisElement).call(yAxis).selectAll('text').attr('aria-hidden', 'true') : '';
     axisData.yAxisDomainValues = domainValues;
     return yAxisScale;
@@ -1214,21 +1414,6 @@ export var CustomPoints;
         'aria-describedby': accessibleData.ariaDescribedBy
     };
 };
-export const convertToLocaleString = (data, culture)=>{
-    if (data === undefined || data === null || Number.isNaN(data)) {
-        return data;
-    }
-    culture = culture || undefined;
-    if (typeof data === 'number') {
-        return data.toLocaleString(culture);
-    } else if (typeof data === 'string' && !isNaN(Number(data))) {
-        const num = Number(data);
-        return num.toLocaleString(culture);
-    } else if (data instanceof Date) {
-        return data.toLocaleDateString(culture);
-    }
-    return data;
-};
 export function rotateXAxisLabels(rotateLabelProps) {
     const { node, xAxis } = rotateLabelProps;
     if (node === null || xAxis === null) {
@@ -1286,14 +1471,8 @@ export function wrapTextInsideDonut(selectorClass, maxWidth) {
         idx += 1;
     });
 }
-export function formatValueWithSIPrefix(value) {
-    let specifier;
-    if (value < 1000) {
-        specifier = '.2~'; // upto 2 decimal places without insignificant trailing zeros
-    } else {
-        specifier = '.1'; // upto 1 decimal place
-    }
-    return d3FormatPrefix(specifier, value)(value);
+export function formatScientificLimitWidth(value) {
+    return yAxisTickFormatterInternal(value, true);
 }
 const DEFAULT_BAR_WIDTH = 16;
 const MIN_BAR_WIDTH = 1;