refactor(plugins): Time Comparison Utils (apache#27145)

(cherry picked from commit 127df24)

superset-frontend/packages/superset-ui-core/src/index.ts

@@ -37,3 +37,4 @@ export * from './math-expression';
 export * from './ui-overrides';
 export * from './hooks';
 export * from './currency-format';
+export * from './time-comparison';

superset-frontend/packages/superset-ui-core/src/query/types/Query.ts

@@ -69,6 +69,8 @@ export type QueryObjectExtras = Partial<{
   time_grain_sqla?: TimeGranularity;
   /** WHERE condition */
   where?: string;
+  /** Instant Time Comparison */
+  instant_time_comparison_range?: string;
 }>;
 
 export type ResidualQueryObjectData = {

superset-frontend/packages/superset-ui-core/src/time-comparison/README.md

@@ -0,0 +1,47 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## @superset-ui/core/time-comparison
+
+This is a collection of methods used to support Time Comparison in charts.
+
+#### Example usage
+
+```js
+import { getComparisonTimeRangeInfo } from '@superset-ui/core';
+const { since, until } = getComparisonTimeRangeInfo(
+  adhocFilters,
+  extraFormData,
+);
+console.log(adhocFilters, extraFormData);
+```
+
+or
+
+```js
+import { ComparisonTimeRangeType } from '@superset-ui/core';
+ComparisonTimeRangeType.Custom; // 'c'
+ComparisonTimeRangeType.InheritRange; // 'r'
+```
+
+#### API
+
+`fn(args)`
+
+- Do something

superset-frontend/packages/superset-ui-core/src/time-comparison/getComparisonFilters.ts

@@ -0,0 +1,67 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { QueryFormData } from '../query';
+import { AdhocFilter } from '../types';
+
+/**
+ * This method is used to get the query filters to be applied to the comparison query after
+ * overriding the time range in case an extra form data is provided.
+ * For example when rendering a chart that uses time comparison in a dashboard with time filters.
+ * @param formData - the form data
+ * @param extraFormData - the extra form data
+ * @returns the query filters to be applied to the comparison query
+ */
+export const getComparisonFilters = (
+  formData: QueryFormData,
+  extraFormData: any,
+): AdhocFilter[] => {
+  const timeFilterIndex: number =
+    formData.adhoc_filters?.findIndex(
+      filter => 'operator' in filter && filter.operator === 'TEMPORAL_RANGE',
+    ) ?? -1;
+
+  const timeFilter: AdhocFilter | null =
+    timeFilterIndex !== -1 && formData.adhoc_filters
+      ? formData.adhoc_filters[timeFilterIndex]
+      : null;
+
+  if (
+    timeFilter &&
+    'comparator' in timeFilter &&
+    typeof timeFilter.comparator === 'string'
+  ) {
+    if (extraFormData?.time_range) {
+      timeFilter.comparator = extraFormData.time_range;
+    }
+  }
+
+  const comparisonQueryFilter = timeFilter ? [timeFilter] : [];
+
+  const otherFilters = formData.adhoc_filters?.filter(
+    (_value: any, index: number) => timeFilterIndex !== index,
+  );
+  const comparisonQueryFilters = otherFilters
+    ? [...comparisonQueryFilter, ...otherFilters]
+    : comparisonQueryFilter;
+
+  return comparisonQueryFilters;
+};
+
+export default getComparisonFilters;

superset-frontend/packages/superset-ui-core/src/time-comparison/getComparisonInfo.ts

@@ -0,0 +1,65 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { QueryFormData } from '../query';
+import { getComparisonFilters } from './getComparisonFilters';
+import { ComparisonTimeRangeType } from './types';
+
+/**
+ * This is the main function to get the comparison info. It will return the formData
+ * that a viz can use to query the comparison data and the time shift text needed for
+ * the comparison time range based on the control value.
+ * @param formData
+ * @param timeComparison
+ * @param extraFormData
+ * @returns the processed formData
+ */
+
+export const getComparisonInfo = (
+  formData: QueryFormData,
+  timeComparison: string,
+  extraFormData: any,
+): QueryFormData => {
+  let comparisonFormData;
+
+  if (timeComparison !== ComparisonTimeRangeType.Custom) {
+    comparisonFormData = {
+      ...formData,
+      adhoc_filters: getComparisonFilters(formData, extraFormData),
+      extra_form_data: {
+        ...extraFormData,
+        time_range: undefined,
+      },
+    };
+  } else {
+    // This is when user selects Custom as time comparison
+    comparisonFormData = {
+      ...formData,
+      adhoc_filters: formData.adhoc_custom,
+      extra_form_data: {
+        ...extraFormData,
+        time_range: undefined,
+      },
+    };
+  }
+
+  return comparisonFormData;
+};
+
+export default getComparisonInfo;

superset-frontend/packages/superset-ui-core/src/time-comparison/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export * from './types';
+
+export { default as getComparisonInfo } from './getComparisonInfo';
+export { default as getComparisonFilters } from './getComparisonFilters';

superset-frontend/packages/superset-ui-core/src/time-comparison/types.ts

@@ -0,0 +1,30 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Supported comparison time ranges
+ */
+
+export enum ComparisonTimeRangeType {
+  Custom = 'c',
+  InheritedRange = 'r',
+  Month = 'm',
+  Week = 'w',
+  Year = 'y',
+}

superset-frontend/packages/superset-ui-core/src/validator/index.ts

@@ -24,3 +24,4 @@ export { default as validateNumber } from './validateNumber';
 export { default as validateNonEmpty } from './validateNonEmpty';
 export { default as validateMaxValue } from './validateMaxValue';
 export { default as validateMapboxStylesUrl } from './validateMapboxStylesUrl';
+export { default as validateTimeComparisonRangeValues } from './validateTimeComparisonRangeValues';

superset-frontend/packages/superset-ui-core/src/validator/validateTimeComparisonRangeValues.ts

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { ComparisonTimeRangeType } from '../time-comparison';
+import { t } from '../translation';
+import { ensureIsArray } from '../utils';
+
+export const validateTimeComparisonRangeValues = (
+  timeRangeValue?: any,
+  controlValue?: any,
+) => {
+  const isCustomTimeRange = timeRangeValue === ComparisonTimeRangeType.Custom;
+  const isCustomControlEmpty = controlValue?.every(
+    (val: any) => ensureIsArray(val).length === 0,
+  );
+  return isCustomTimeRange && isCustomControlEmpty
+    ? [t('Filters for comparison must have a value')]
+    : [];
+};
+
+export default validateTimeComparisonRangeValues;