@formant/ava 3.5.0-formant → 3.5.2-formant

package/esm/insight/chart/strategy/augmentedMarks/changePoint.js

@@ -1,6 +1,6 @@
 import { __read, __spreadArray } from "tslib";
 import { size } from 'lodash';
-import { dataFormat } from '../../../../utils';
+import { dataFormat, formatInsightDate } from '../../../../utils';
 import { pointMarkStrategy } from '../commonMarks';
 import { insight2ChartStrategy } from '../chart';
 import { augmentedMarks2Marks } from '../../utils';
@@ -14,7 +14,7 @@ export var changePointAugmentedMarksStrategy = function (insight) {
             pointMarkStrategy([pattern], {
                 role: 'highlight',
                 name: 'change point',
-                label: function (pt) { return "".concat(pt.x, ", ").concat(measure, ": ").concat(dataFormat(pt.y)); },
+                label: function (pt) { return "".concat(formatInsightDate(pt.x), " \u00B7 ").concat(measure, ": ").concat(dataFormat(pt.y)); },
             }),
         ],
     }); });

package/esm/insight/narrative/strategy/changePoint.js

@@ -2,6 +2,7 @@ import { __extends } from "tslib";
 /* eslint-disable no-template-curly-in-string */
 import { first, last } from 'lodash';
 import { generateTextSpec } from '../../../ntv';
+import { formatInsightDateRange } from '../../../utils/dateFormat';
 import { InsightNarrativeStrategy } from './base';
 var variableMetaMap = {
     dateRange: {
@@ -25,7 +26,7 @@ var ChangePointNarrativeStrategy = /** @class */ (function (_super) {
         var spec = generateTextSpec({
             structures: ChangePointNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat(first(data)[dimension], "~").concat(last(data)[dimension]),
+                dateRange: formatInsightDateRange(first(data)[dimension], last(data)[dimension]),
                 measure: patterns[0].measure,
                 total: patterns.length,
             },

package/esm/insight/narrative/strategy/timeSeriesOutlier.js

@@ -4,8 +4,7 @@ import { first, last, maxBy, minBy } from 'lodash';
 import { generateTextSpec } from '../../../ntv';
 import { InsightNarrativeStrategy } from './base';
 import { getDiffDesc } from './helpers';
-import { formatDateRange } from "little-date";
-import { format } from 'date-fns';
+import { formatInsightDate, formatInsightDateRange } from '../../../utils/dateFormat';
 var variableMetaMap = {
     dateRange: {
         varType: 'time_desc',
@@ -46,7 +45,7 @@ var TimeSeriesOutlierNarrativeStrategy = /** @class */ (function (_super) {
         var spec = generateTextSpec({
             structures: TimeSeriesOutlierNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat(formatDateRange(new Date(first(data)[dimension]), new Date(last(data)[dimension]), { includeTime: false })),
+                dateRange: formatInsightDateRange(first(data)[dimension], last(data)[dimension]),
                 total: patterns.length,
                 measure: measure,
                 max: maxBy(data, measure)[measure],
@@ -54,7 +53,7 @@ var TimeSeriesOutlierNarrativeStrategy = /** @class */ (function (_super) {
                 outliers: patterns.map(function (point) {
                     var base = point.baselines[point.index];
                     var diff = point.y - base;
-                    return __assign(__assign({}, point), { base: base, diffDesc: getDiffDesc(diff, lang), x: format(new Date(point.x), 'MMM d, yyyy'), diff: diff });
+                    return __assign(__assign({}, point), { base: base, diffDesc: getDiffDesc(diff, lang), x: formatInsightDate(point.x), diff: diff });
                 }),
             },
         });

package/esm/insight/narrative/strategy/trend.js

@@ -2,8 +2,8 @@ import { __extends } from "tslib";
 /* eslint-disable no-template-curly-in-string */
 import { first, last } from 'lodash';
 import { generateTextSpec } from '../../../ntv';
+import { formatInsightDateRange } from '../../../utils/dateFormat';
 import { InsightNarrativeStrategy } from './base';
-import { formatDateRange } from "little-date";
 var trendMapping = {
     decreasing: '下降',
     increasing: '上升',
@@ -32,7 +32,7 @@ var TrendNarrativeStrategy = /** @class */ (function (_super) {
         var spec = generateTextSpec({
             structures: TrendNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat(formatDateRange(new Date(first(data)[dimension]), new Date(last(data)[dimension]), { includeTime: false })),
+                dateRange: formatInsightDateRange(first(data)[dimension], last(data)[dimension]),
                 measure: measure,
                 trend: lang === 'en-US' ? trend : trendMapping[trend],
                 slope: regression.equation[0],

package/esm/utils/dateFormat.js

@@ -0,0 +1,44 @@
+import { format } from 'date-fns';
+import { formatDateRange } from 'little-date';
+// 2025-03-19, 2025-03-19 00:00:00, 2025-03-19T00:00:00.000Z, 2025-03-19T00:00:00+02:00
+var ISO_LIKE = /^\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+ * Parse an insight dimension value as a date. Only ISO-like strings and Date objects count;
+ * zone-less values are local time. `new Date('2025-03-19 00:00:00')` is non-standard (older
+ * Safari rejects it), so the space is normalised to `T` first.
+ */
+export var parseInsightDate = function (value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value !== 'string' || !ISO_LIKE.test(value))
+        return undefined;
+    var date = new Date(value.length === 10 ? "".concat(value, "T00:00:00") : value.replace(' ', 'T'));
+    return Number.isNaN(date.getTime()) ? undefined : date;
+};
+// a zone designator means an absolute instant (e.g. an hourly UTC bucket): always show its time
+var ZONED = /\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/;
+/**
+ * Whether to print a time of day. Zoned instants always do, so an hourly series reads
+ * `Oct 6, 23:00`, `Oct 7, 00:00` rather than switching to a date at local midnight. Zone-less
+ * values only do when the clock is not midnight (`2025-03-19 00:00:00` is a daily bucket).
+ */
+var showsTime = function (value, date) {
+    return value instanceof Date || (typeof value === 'string' && ZONED.test(value))
+        ? true
+        : date.getHours() !== 0 || date.getMinutes() !== 0;
+};
+/** `Oct 7, 2026`, or `Oct 7, 14:00` when the value carries a time of day; non-dates pass through */
+export var formatInsightDate = function (value) {
+    var date = parseInsightDate(value);
+    if (!date)
+        return String(value);
+    return format(date, showsTime(value, date) ? 'MMM d, HH:mm' : 'MMM d, yyyy');
+};
+/** `Oct 6 - 7, 2026` style range (little-date); non-dates fall back to `start ~ end` */
+export var formatInsightDateRange = function (start, end) {
+    var from = parseInsightDate(start);
+    var to = parseInsightDate(end);
+    if (!from || !to)
+        return "".concat(start, "~").concat(end);
+    return formatDateRange(from, to, { includeTime: false });
+};

package/esm/utils/index.js

@@ -1,3 +1,4 @@
 export * from './isType';
 export * from './arr2map';
 export { default as dataFormat } from './dataFormat';
+export { parseInsightDate, formatInsightDate, formatInsightDateRange } from './dateFormat';

package/lib/insight/chart/strategy/augmentedMarks/changePoint.js

@@ -17,7 +17,7 @@ var changePointAugmentedMarksStrategy = function (insight) {
             (0, commonMarks_1.pointMarkStrategy)([pattern], {
                 role: 'highlight',
                 name: 'change point',
-                label: function (pt) { return "".concat(pt.x, ", ").concat(measure, ": ").concat((0, utils_1.dataFormat)(pt.y)); },
+                label: function (pt) { return "".concat((0, utils_1.formatInsightDate)(pt.x), " \u00B7 ").concat(measure, ": ").concat((0, utils_1.dataFormat)(pt.y)); },
             }),
         ],
     }); });

package/lib/insight/narrative/strategy/changePoint.js

@@ -4,6 +4,7 @@ var tslib_1 = require("tslib");
 /* eslint-disable no-template-curly-in-string */
 var lodash_1 = require("lodash");
 var ntv_1 = require("../../../ntv");
+var dateFormat_1 = require("../../../utils/dateFormat");
 var base_1 = require("./base");
 var variableMetaMap = {
     dateRange: {
@@ -27,7 +28,7 @@ var ChangePointNarrativeStrategy = /** @class */ (function (_super) {
         var spec = (0, ntv_1.generateTextSpec)({
             structures: ChangePointNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat((0, lodash_1.first)(data)[dimension], "~").concat((0, lodash_1.last)(data)[dimension]),
+                dateRange: (0, dateFormat_1.formatInsightDateRange)((0, lodash_1.first)(data)[dimension], (0, lodash_1.last)(data)[dimension]),
                 measure: patterns[0].measure,
                 total: patterns.length,
             },

package/lib/insight/narrative/strategy/timeSeriesOutlier.js

@@ -6,8 +6,7 @@ var lodash_1 = require("lodash");
 var ntv_1 = require("../../../ntv");
 var base_1 = require("./base");
 var helpers_1 = require("./helpers");
-var little_date_1 = require("little-date");
-var date_fns_1 = require("date-fns");
+var dateFormat_1 = require("../../../utils/dateFormat");
 var variableMetaMap = {
     dateRange: {
         varType: 'time_desc',
@@ -48,7 +47,7 @@ var TimeSeriesOutlierNarrativeStrategy = /** @class */ (function (_super) {
         var spec = (0, ntv_1.generateTextSpec)({
             structures: TimeSeriesOutlierNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat((0, little_date_1.formatDateRange)(new Date((0, lodash_1.first)(data)[dimension]), new Date((0, lodash_1.last)(data)[dimension]), { includeTime: false })),
+                dateRange: (0, dateFormat_1.formatInsightDateRange)((0, lodash_1.first)(data)[dimension], (0, lodash_1.last)(data)[dimension]),
                 total: patterns.length,
                 measure: measure,
                 max: (0, lodash_1.maxBy)(data, measure)[measure],
@@ -56,7 +55,7 @@ var TimeSeriesOutlierNarrativeStrategy = /** @class */ (function (_super) {
                 outliers: patterns.map(function (point) {
                     var base = point.baselines[point.index];
                     var diff = point.y - base;
-                    return tslib_1.__assign(tslib_1.__assign({}, point), { base: base, diffDesc: (0, helpers_1.getDiffDesc)(diff, lang), x: (0, date_fns_1.format)(new Date(point.x), 'MMM d, yyyy'), diff: diff });
+                    return tslib_1.__assign(tslib_1.__assign({}, point), { base: base, diffDesc: (0, helpers_1.getDiffDesc)(diff, lang), x: (0, dateFormat_1.formatInsightDate)(point.x), diff: diff });
                 }),
             },
         });

package/lib/insight/narrative/strategy/trend.js

@@ -4,8 +4,8 @@ var tslib_1 = require("tslib");
 /* eslint-disable no-template-curly-in-string */
 var lodash_1 = require("lodash");
 var ntv_1 = require("../../../ntv");
+var dateFormat_1 = require("../../../utils/dateFormat");
 var base_1 = require("./base");
-var little_date_1 = require("little-date");
 var trendMapping = {
     decreasing: '下降',
     increasing: '上升',
@@ -34,7 +34,7 @@ var TrendNarrativeStrategy = /** @class */ (function (_super) {
         var spec = (0, ntv_1.generateTextSpec)({
             structures: TrendNarrativeStrategy.structures[lang],
             variable: {
-                dateRange: "".concat((0, little_date_1.formatDateRange)(new Date((0, lodash_1.first)(data)[dimension]), new Date((0, lodash_1.last)(data)[dimension]), { includeTime: false })),
+                dateRange: (0, dateFormat_1.formatInsightDateRange)((0, lodash_1.first)(data)[dimension], (0, lodash_1.last)(data)[dimension]),
                 measure: measure,
                 trend: lang === 'en-US' ? trend : trendMapping[trend],
                 slope: regression.equation[0],

package/lib/utils/dateFormat.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parse an insight dimension value as a date. Only ISO-like strings and Date objects count;
+ * zone-less values are local time. `new Date('2025-03-19 00:00:00')` is non-standard (older
+ * Safari rejects it), so the space is normalised to `T` first.
+ */
+export declare const parseInsightDate: (value: unknown) => Date | undefined;
+/** `Oct 7, 2026`, or `Oct 7, 14:00` when the value carries a time of day; non-dates pass through */
+export declare const formatInsightDate: (value: unknown) => string;
+/** `Oct 6 - 7, 2026` style range (little-date); non-dates fall back to `start ~ end` */
+export declare const formatInsightDateRange: (start: unknown, end: unknown) => string;

package/lib/utils/dateFormat.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatInsightDateRange = exports.formatInsightDate = exports.parseInsightDate = void 0;
+var date_fns_1 = require("date-fns");
+var little_date_1 = require("little-date");
+// 2025-03-19, 2025-03-19 00:00:00, 2025-03-19T00:00:00.000Z, 2025-03-19T00:00:00+02:00
+var ISO_LIKE = /^\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+ * Parse an insight dimension value as a date. Only ISO-like strings and Date objects count;
+ * zone-less values are local time. `new Date('2025-03-19 00:00:00')` is non-standard (older
+ * Safari rejects it), so the space is normalised to `T` first.
+ */
+var parseInsightDate = function (value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value !== 'string' || !ISO_LIKE.test(value))
+        return undefined;
+    var date = new Date(value.length === 10 ? "".concat(value, "T00:00:00") : value.replace(' ', 'T'));
+    return Number.isNaN(date.getTime()) ? undefined : date;
+};
+exports.parseInsightDate = parseInsightDate;
+// a zone designator means an absolute instant (e.g. an hourly UTC bucket): always show its time
+var ZONED = /\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/;
+/**
+ * Whether to print a time of day. Zoned instants always do, so an hourly series reads
+ * `Oct 6, 23:00`, `Oct 7, 00:00` rather than switching to a date at local midnight. Zone-less
+ * values only do when the clock is not midnight (`2025-03-19 00:00:00` is a daily bucket).
+ */
+var showsTime = function (value, date) {
+    return value instanceof Date || (typeof value === 'string' && ZONED.test(value))
+        ? true
+        : date.getHours() !== 0 || date.getMinutes() !== 0;
+};
+/** `Oct 7, 2026`, or `Oct 7, 14:00` when the value carries a time of day; non-dates pass through */
+var formatInsightDate = function (value) {
+    var date = (0, exports.parseInsightDate)(value);
+    if (!date)
+        return String(value);
+    return (0, date_fns_1.format)(date, showsTime(value, date) ? 'MMM d, HH:mm' : 'MMM d, yyyy');
+};
+exports.formatInsightDate = formatInsightDate;
+/** `Oct 6 - 7, 2026` style range (little-date); non-dates fall back to `start ~ end` */
+var formatInsightDateRange = function (start, end) {
+    var from = (0, exports.parseInsightDate)(start);
+    var to = (0, exports.parseInsightDate)(end);
+    if (!from || !to)
+        return "".concat(start, "~").concat(end);
+    return (0, little_date_1.formatDateRange)(from, to, { includeTime: false });
+};
+exports.formatInsightDateRange = formatInsightDateRange;

package/lib/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from './isType';
 export * from './arr2map';
 export { default as dataFormat } from './dataFormat';
+export { parseInsightDate, formatInsightDate, formatInsightDateRange } from './dateFormat';

package/lib/utils/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dataFormat = void 0;
+exports.formatInsightDateRange = exports.formatInsightDate = exports.parseInsightDate = exports.dataFormat = void 0;
 var tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./isType"), exports);
 tslib_1.__exportStar(require("./arr2map"), exports);
 var dataFormat_1 = require("./dataFormat");
 Object.defineProperty(exports, "dataFormat", { enumerable: true, get: function () { return tslib_1.__importDefault(dataFormat_1).default; } });
+var dateFormat_1 = require("./dateFormat");
+Object.defineProperty(exports, "parseInsightDate", { enumerable: true, get: function () { return dateFormat_1.parseInsightDate; } });
+Object.defineProperty(exports, "formatInsightDate", { enumerable: true, get: function () { return dateFormat_1.formatInsightDate; } });
+Object.defineProperty(exports, "formatInsightDateRange", { enumerable: true, get: function () { return dateFormat_1.formatInsightDateRange; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formant/ava",
-  "version": "3.5.0-formant",
+  "version": "3.5.2-formant",
   "description": "A framework for automated visual analytics.",
   "author": {
     "name": "formant",