Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

fix(layers): show timestamp text labels as a readable date time (#3810)

Igor Dykhtac9f6ecb791a7
diff --git a/src/layers/src/base-layer.ts b/src/layers/src/base-layer.ts
index c637668f1..aba2293f5 100644
--- a/src/layers/src/base-layer.ts
+++ b/src/layers/src/base-layer.ts
@@ -1405,7 +1405,9 @@ class Layer implements KeplerLayer {
...(this.config.textLabel || []).reduce(
(accu, tl, i) => ({
...accu,
- [`getLabelCharacterSet-${i}`]: tl.field ? tl.field.name : null
+ [`getLabelCharacterSet-${i}`]: tl.field
+ ? {name: tl.field.name, displayFormat: tl.field.displayFormat}
+ : null
}),
{}
)
@@ -1803,6 +1805,7 @@ class Layer implements KeplerLayer {
...updateTriggers,
getText: {
field: textLabel[i].field?.name,
+ displayFormat: textLabel[i].field?.displayFormat,
...(updateTriggers.getText || {})
},
getPixelOffset: {
diff --git a/src/layers/src/layer-text-label.spec.ts b/src/layers/src/layer-text-label.spec.ts
new file mode 100644
index 000000000..5cd1eec65
--- /dev/null
+++ b/src/layers/src/layer-text-label.spec.ts
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import KeplerTable from '@kepler.gl/table';
+import {ALL_FIELD_TYPES, DEFAULT_TEXT_LABEL} from '@kepler.gl/constants';
+import PointLayer from './point-layer/point-layer';
+import {formatTextLabelData, getSingleTextLabelValue} from './layer-text-label';
+
+async function makeTable() {
+ const table = new KeplerTable({color: [255, 0, 0]} as any);
+ await table.importData({
+ data: {
+ rows: [
+ [37.77, -122.42, '2021-01-01 03:12:00', 3.5],
+ [37.78, -122.41, null, 1.25],
+ [37.79, -122.4, '1970-01-01 00:00:00', 2.5]
+ ],
+ fields: [
+ {name: 'latitude', type: ALL_FIELD_TYPES.real},
+ {name: 'longitude', type: ALL_FIELD_TYPES.real},
+ {name: 'time', type: ALL_FIELD_TYPES.timestamp, format: 'YYYY-M-D H:m:s'},
+ {name: 'value', type: ALL_FIELD_TYPES.real}
+ ]
+ } as any
+ });
+ return table;
+}
+
+function getTextLabels(table: KeplerTable, field) {
+ return formatTextLabelData({
+ textLabel: [{field}],
+ oldLayerData: null,
+ data: [{index: 0}, {index: 1}, {index: 2}],
+ dataContainer: table.dataContainer
+ });
+}
+
+const findField = (table: KeplerTable, name: string) => table.fields.find(f => f.name === name);
+
+describe('formatTextLabelData', () => {
+ test('shows timestamp labels as a date time instead of unix milliseconds', async () => {
+ const table = await makeTable();
+ const [{getText}] = getTextLabels(table, findField(table, 'time'));
+
+ expect(getText({index: 0})).toBe('01/01/2021 3:12:00 AM');
+ expect(getText({index: 1})).toBe('');
+ expect(getText({index: 2})).toBe('01/01/1970 12:00:00 AM');
+ });
+
+ test('uses the display format of a timestamp field', async () => {
+ const table = await makeTable();
+ const field = {...findField(table, 'time'), displayFormat: 'YYYY-MM-DD HH:mm'};
+ const [{getText, characterSet}] = getTextLabels(table, field);
+
+ expect(getText({index: 0})).toBe('2021-01-01 03:12');
+ expect(characterSet).toEqual(expect.arrayContaining(['2', '0', '1', '-', ' ', '3', ':']));
+ });
+
+ test('keeps the raw value for labels of other field types', async () => {
+ const table = await makeTable();
+ const [{getText}] = getTextLabels(table, findField(table, 'value'));
+
+ expect(getText({index: 0})).toBe('3.5');
+ expect(getText({index: 1})).toBe('1.25');
+ });
+});
+
+describe('getSingleTextLabelValue', () => {
+ test('formats a timestamp read from a materialized row', async () => {
+ const table = await makeTable();
+ const field = findField(table, 'time');
+ const row = table.dataContainer.rowAsArray(0);
+
+ expect(getSingleTextLabelValue({field, format: ''}, row)).toBe('01/01/2021 3:12:00 AM');
+ });
+});
+
+describe('renderTextLabelLayer', () => {
+ test('includes the display format in the deck.gl text update trigger', async () => {
+ const table = await makeTable();
+ const field = {...findField(table, 'time')!, displayFormat: 'YYYY'};
+ const layer = new PointLayer({id: 'point', dataId: 'data'});
+ layer.updateLayerConfig({
+ textLabel: [{...DEFAULT_TEXT_LABEL, field}]
+ });
+
+ const [textLayer] = layer.renderTextLabelLayer(
+ {
+ getPixelOffset: () => [0, 0],
+ updateTriggers: {},
+ sharedProps: {}
+ },
+ {
+ data: {
+ data: [],
+ textLabels: [{getText: () => '', characterSet: []}]
+ },
+ mapState: {},
+ visible: true
+ }
+ );
+
+ expect(textLayer.props.updateTriggers.getText).toEqual({
+ field: 'time',
+ displayFormat: 'YYYY'
+ });
+ });
+});
diff --git a/src/layers/src/layer-text-label.ts b/src/layers/src/layer-text-label.ts
index d65768d8c..73c4bb316 100644
--- a/src/layers/src/layer-text-label.ts
+++ b/src/layers/src/layer-text-label.ts
@@ -10,6 +10,7 @@ import {
getFormatter
} from '@kepler.gl/utils';
import {notNullorUndefined, toArray} from '@kepler.gl/common-utils';
+import {ALL_FIELD_TYPES, TOOLTIP_FORMATS, TOOLTIP_KEY} from '@kepler.gl/constants';
import uniq from 'es-toolkit/compat/uniq';
import {max} from 'd3-array';
@@ -45,15 +46,31 @@ export function getTextOffsetByRadius(radiusScale, getRadius, mapState) {
// eslint-disable-next-line @typescript-eslint/no-unused-vars
export const textLabelAccessor = textLabel => dc => d => {
- const val = textLabel.field.valueAccessor(d);
+ const {field} = textLabel;
+ if (field.type === ALL_FIELD_TYPES.timestamp) {
+ return getSingleTextLabelValue(textLabel, d);
+ }
+ const val = field.valueAccessor(d);
return notNullorUndefined(val) ? String(val) : '';
};
+/**
+ * Timestamp value accessors return unix milliseconds, so a timestamp label without a
+ * display format falls back to the date time format tooltips use for timestamps by default.
+ */
+const getTextLabelFormat = (field: any, format?: string): string | undefined => {
+ const labelFormat = field.displayFormat ?? format;
+ if (!labelFormat && field.type === ALL_FIELD_TYPES.timestamp) {
+ return TOOLTIP_FORMATS.DATE_TIME_L_LTS[TOOLTIP_KEY];
+ }
+ return labelFormat;
+};
+
export const getSingleTextLabelValue = (
{field, format}: {field: any; format?: string},
datum: {index: number} | any[] | null
): string => {
- const fmt = getFormatter(field.displayFormat ?? format, field);
+ const fmt = getFormatter(getTextLabelFormat(field, format), field);
const val = datum ? field.valueAccessor(datum, true) : null;
return (notNullorUndefined(val) ? fmt(val) : null) ?? '';
};
diff --git a/src/reducers/src/vis-state-updaters.ts b/src/reducers/src/vis-state-updaters.ts
index 0e65d2a41..62f856eaa 100644
--- a/src/reducers/src/vis-state-updaters.ts
+++ b/src/reducers/src/vis-state-updaters.ts
@@ -5679,22 +5679,60 @@ export function setColumnDisplayFormatUpdater(
const newDataset = copyTableAndUpdate(dataset, {fields: newFields as Field[]});
let newState = pick_('datasets')(merge_({[dataId]: newDataset}))(state);
+ const textLabelLayerIndexes: number[] = [];
- // update colorField displayFormat
+ // Layer configs retain their own field objects, so keep those copies in sync
+ // with the display format stored on the dataset field.
newState = {
...newState,
- layers: newState.layers.map(layer =>
- layer.config?.colorField?.name && layer.config.colorField.name in formats
+ layers: newState.layers.map((layer, layerIndex) => {
+ // Column names are not unique across datasets. Only update layers that
+ // belong to the dataset targeted by this action.
+ if (layer.config.dataId !== dataId) {
+ return layer;
+ }
+
+ const colorField = layer.config?.colorField;
+ const updatedColorField =
+ colorField?.name && colorField.name in formats
+ ? {...colorField, displayFormat: formats[colorField.name]}
+ : null;
+ // Text labels also keep field copies instead of reading dataset.fields at render time.
+ const textLabel = layer.config.textLabel.map(label => {
+ const {field} = label;
+ return field?.name && field.name in formats
+ ? {...label, field: {...field, displayFormat: formats[field.name]}}
+ : label;
+ });
+ const updateTextLabel = textLabel.some(
+ (label, index) => label !== layer.config.textLabel[index]
+ );
+ if (updateTextLabel) {
+ textLabelLayerIndexes.push(layerIndex);
+ }
+
+ return updatedColorField || updateTextLabel
? layer.updateLayerConfig({
- colorField: {
- ...layer.config.colorField,
- displayFormat: formats[layer.config.colorField.name]
- }
+ ...(updatedColorField ? {colorField: updatedColorField} : {}),
+ ...(updateTextLabel ? {textLabel} : {})
})
- : layer
- )
+ : layer;
+ })
};
+ if (textLabelLayerIndexes.length) {
+ // Label accessors and character sets are cached in layerData. Rebuild them
+ // immediately so the new format appears without removing and re-adding the label field.
+ const layers = newState.layers.slice();
+ const layerData = newState.layerData.slice();
+ textLabelLayerIndexes.forEach(layerIndex => {
+ const result = calculateLayerData(layers[layerIndex], newState, layerData[layerIndex]);
+ layers[layerIndex] = result.layer;
+ layerData[layerIndex] = result.layerData;
+ });
+ newState = {...newState, layers, layerData};
+ }
+
return newState;
}
diff --git a/src/utils/src/data-utils.ts b/src/utils/src/data-utils.ts
index b2d713678..8935a95c4 100644
--- a/src/utils/src/data-utils.ts
+++ b/src/utils/src/data-utils.ts
@@ -545,6 +545,6 @@ export function datetimeFormatter(
): (format?: string) => (ts: number) => string {
return timezone
? format => ts => moment.utc(ts).tz(timezone).format(format)
- : // return empty string instead of 'Invalid date' if ts is undefined/null
- format => ts => ts ? moment.utc(ts).format(format) : '';
+ : // return empty string for missing values, while preserving Unix epoch zero
+ format => ts => ts || ts === 0 ? moment.utc(ts).format(format) : '';
}
diff --git a/test/node/reducers/vis-state-test.js b/test/node/reducers/vis-state-test.js
index a4946c927..68f96db1b 100644
--- a/test/node/reducers/vis-state-test.js
+++ b/test/node/reducers/vis-state-test.js
@@ -28,7 +28,7 @@ import {
import {processCsvData, processGeojson, remoteDatasetFromUrl} from '@kepler.gl/processors';
import {Layer, KeplerGlLayers, COLUMN_MODE_TABLE} from '@kepler.gl/layers';
-import {maybeToDate} from '@kepler.gl/table';
+import {copyTableAndUpdate, maybeToDate} from '@kepler.gl/table';
import {
createDataContainer,
applyFilterFieldName,
@@ -1284,6 +1284,79 @@ test('#visStateReducer -> LAYER_TEXT_LABEL_CHANGE', t => {
t.end();
});
+test('#visStateReducer -> SET_COLUMN_DISPLAY_FORMAT updates text labels', t => {
+ const initialState = CloneDeep(StateWFiles.visState);
+ const otherDataId = 'other-data';
+ const otherDataset = copyTableAndUpdate(initialState.datasets[testCsvDataId], {
+ id: otherDataId
+ });
+ const layerIndex = initialState.layers.findIndex(layer => layer.config.dataId === testCsvDataId);
+ const field = initialState.datasets[testCsvDataId].fields.find(
+ ({name}) => name === 'gps_data.utc_timestamp'
+ );
+ const otherField = otherDataset.fields.find(({name}) => name === 'gps_data.utc_timestamp');
+ const layer = CloneDeep(initialState.layers[layerIndex]).updateLayerConfig({
+ textLabel: [{...DEFAULT_TEXT_LABEL, field}]
+ });
+ const otherLayer = CloneDeep(initialState.layers[layerIndex]).updateLayerConfig({
+ dataId: otherDataId,
+ textLabel: [{...DEFAULT_TEXT_LABEL, field: otherField}]
+ });
+ otherLayer.id = `${otherLayer.id}-other`;
+ const stateWithOtherDataset = {
+ ...initialState,
+ datasets: {...initialState.datasets, [otherDataId]: otherDataset}
+ };
+ const {layerData: oldLayerData} = calculateLayerData(layer, stateWithOtherDataset);
+ const {layerData: otherLayerData} = calculateLayerData(otherLayer, stateWithOtherDataset);
+ const layers = stateWithOtherDataset.layers.slice();
+ const layerData = stateWithOtherDataset.layerData.slice();
+ layers[layerIndex] = layer;
+ layerData[layerIndex] = oldLayerData;
+ const otherLayerIndex = layers.push(otherLayer) - 1;
+ layerData.push(otherLayerData);
+ const stateWithTextLabel = {
+ ...stateWithOtherDataset,
+ layers,
+ layerData
+ };
+
+ const nextState = reducer(
+ stateWithTextLabel,
+ VisStateActions.setColumnDisplayFormat(testCsvDataId, {
+ 'gps_data.utc_timestamp': 'YYYY'
+ })
+ );
+ const updatedLayer = nextState.layers[layerIndex];
+
+ t.equal(
+ updatedLayer.config.textLabel[0].field.displayFormat,
+ 'YYYY',
+ 'should update the display format stored in the text label field'
+ );
+ t.equal(
+ nextState.layerData[layerIndex].textLabels[0].getText({index: 0}),
+ '2016',
+ 'should immediately rebuild cached text labels with the updated display format'
+ );
+ t.equal(
+ nextState.layers[otherLayerIndex],
+ otherLayer,
+ 'should not update a layer belonging to another dataset with the same field name'
+ );
+ t.equal(
+ nextState.layers[otherLayerIndex].config.textLabel[0].field.displayFormat,
+ undefined,
+ 'should leave the other dataset label format unchanged'
+ );
+ t.equal(
+ nextState.layerData[otherLayerIndex],
+ otherLayerData,
+ 'should not rebuild layer data belonging to another dataset'
+ );
+ t.end();
+});
+
test('#visStateReducer -> REORDER_LAYER', t => {
const newReducer = reducer(
{layers: [], layerOrder: [0, 1, 2]},
diff --git a/test/node/utils/data-utils-test.js b/test/node/utils/data-utils-test.js
index 339b792f1..060d054f2 100644
--- a/test/node/utils/data-utils-test.js
+++ b/test/node/utils/data-utils-test.js
@@ -183,6 +183,10 @@ test('dataUtils -> getFormatter', t => {
input: ['L LT'],
assert: ['2011-04-10 00:00', '04/10/2011 12:00 AM']
},
+ {
+ input: ['L LT'],
+ assert: [0, '01/01/1970 12:00 AM']
+ },
{
input: ['L LT'],
assert: [null, '']