feat(Chart): Save Chart State globally (#35343)

Author: alexandrusoare

superset-embedded-sdk/src/index.ts

@@ -89,7 +89,8 @@ export type EmbeddedDashboard = {
   observeDataMask: (
     callbackFn: ObserveDataMaskCallbackFn,
   ) => void;
-  getDataMask: () => Record<string, any>;
+  getDataMask: () => Promise<Record<string, any>>;
+  getChartStates: () => Promise<Record<string, any>>;
   setThemeConfig: (themeConfig: Record<string, any>) => void;
 };
 
@@ -244,6 +245,7 @@ export async function embedDashboard({
     ourPort.get<string>('getDashboardPermalink', { anchor });
   const getActiveTabs = () => ourPort.get<string[]>('getActiveTabs');
   const getDataMask = () => ourPort.get<Record<string, any>>('getDataMask');
+  const getChartStates = () => ourPort.get<Record<string, any>>('getChartStates');
   const observeDataMask = (
     callbackFn: ObserveDataMaskCallbackFn,
   ) => {
@@ -270,6 +272,7 @@ export async function embedDashboard({
     getActiveTabs,
     observeDataMask,
     getDataMask,
+    getChartStates,
     setThemeConfig
   };
 }

superset-frontend/packages/superset-ui-core/src/chart/types/Base.ts

@@ -71,6 +71,44 @@ export type SetDataMaskHook = {
   ({ filterState, extraFormData, ownState }: DataMask): void;
 };
 
+/**
+ * Backend-compatible filter clause for query execution
+ */
+export interface QueryFilterClause {
+  col: string;
+  op: string;
+  val: string | number | string[] | number[];
+}
+
+/**
+ * Backend-compatible sort specification
+ */
+export interface QuerySortBy {
+  id: string;
+  key: string;
+  desc: boolean;
+}
+
+/**
+ * Backend-compatible own state that will be sent to the chart data API.
+ * This represents the standardized format that the backend expects.
+ */
+export interface BackendOwnState {
+  sortBy?: QuerySortBy[];
+  columnOrder?: string[];
+  filters?: QueryFilterClause[];
+  [key: string]: unknown; // Allow additional properties for chart-specific needs
+}
+
+/**
+ * Converter function that transforms chart-specific state to backend format.
+ * Each chart plugin can implement this to convert its internal state representation
+ * to the standardized backend format.
+ */
+export type ChartStateConverter<TChartState = JsonObject> = (
+  chartState: TChartState,
+) => Partial<BackendOwnState>;
+
 export interface PlainObject {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [key: string]: any;

superset-frontend/packages/superset-ui-core/src/components/ThemedAgGridReact/index.tsx

@@ -161,6 +161,7 @@ export type { CustomCellRendererProps } from 'ag-grid-react';
 export type {
   ColDef,
   Column,
+  ColumnState,
   GridOptions,
   GridState,
   GridReadyEvent,

superset-frontend/packages/superset-ui-core/src/types/AgGrid.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 type { ColumnState, SortModelItem } from 'ag-grid-community';
+
+// AG Grid filter type enums
+export enum AgGridFilterType {
+  Text = 'text',
+  Number = 'number',
+  Date = 'date',
+  Set = 'set',
+}
+
+export enum AgGridTextFilterOperator {
+  Equals = 'equals',
+  NotEqual = 'notEqual',
+  Contains = 'contains',
+  NotContains = 'notContains',
+  StartsWith = 'startsWith',
+  EndsWith = 'endsWith',
+  Blank = 'blank',
+  NotBlank = 'notBlank',
+}
+
+export enum AgGridNumberFilterOperator {
+  Equals = 'equals',
+  NotEqual = 'notEqual',
+  LessThan = 'lessThan',
+  LessThanOrEqual = 'lessThanOrEqual',
+  GreaterThan = 'greaterThan',
+  GreaterThanOrEqual = 'greaterThanOrEqual',
+  InRange = 'inRange',
+  Blank = 'blank',
+  NotBlank = 'notBlank',
+}
+
+export interface AgGridSortModel extends SortModelItem {
+  sortIndex?: number;
+}
+
+export interface AgGridFilter {
+  filterType?: string;
+  type?: string;
+  filter?: string | number;
+  filterTo?: number;
+  values?: string[];
+  dateFrom?: string;
+  dateTo?: string;
+  operator?: 'AND' | 'OR';
+  condition1?: AgGridFilter;
+  condition2?: AgGridFilter;
+  conditions?: AgGridFilter[];
+}
+
+export interface AgGridFilterModel {
+  [colId: string]: AgGridFilter;
+}
+
+export interface AgGridChartState {
+  columnState: ColumnState[];
+  sortModel: AgGridSortModel[];
+  filterModel: AgGridFilterModel;
+  columnOrder?: string[];
+  pageSize?: number;
+  currentPage?: number;
+}

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

@@ -20,6 +20,7 @@ import { NumberFormatter } from '../number-format';
 import { CurrencyFormatter } from '../currency-format';
 
 export * from '../query/types';
+export * from './AgGrid';
 
 export type Maybe<T> = T | null;
 

superset-frontend/plugins/plugin-chart-ag-grid-table/src/AgGridTable/index.tsx

@@ -22,25 +22,33 @@ import {
   useMemo,
   useRef,
   memo,
+  FunctionComponent,
   useState,
   ChangeEvent,
   useEffect,
+  type RefObject,
 } from 'react';
 
-import { ThemedAgGridReact } from '@superset-ui/core/components';
+import { Constants, ThemedAgGridReact } from '@superset-ui/core/components';
 import {
   AgGridReact,
   AllCommunityModule,
   ClientSideRowModelModule,
   type ColDef,
+  type ColumnState,
   ModuleRegistry,
   GridReadyEvent,
   GridState,
   CellClickedEvent,
   IMenuActionParams,
 } from '@superset-ui/core/components/ThemedAgGridReact';
-import { type FunctionComponent } from 'react';
-import { JsonObject, DataRecordValue, DataRecord, t } from '@superset-ui/core';
+import {
+  AgGridChartState,
+  DataRecordValue,
+  DataRecord,
+  JsonObject,
+  t,
+} from '@superset-ui/core';
 import { SearchOutlined } from '@ant-design/icons';
 import { debounce, isEqual } from 'lodash';
 import Pagination from './components/Pagination';
@@ -49,6 +57,17 @@ import { SearchOption, SortByItem } from '../types';
 import getInitialSortState, { shouldSort } from '../utils/getInitialSortState';
 import { PAGE_SIZE_OPTIONS } from '../consts';
 
+export interface AgGridState extends Partial<GridState> {
+  timestamp?: number;
+  hasChanges?: boolean;
+}
+
+// AgGridChartState with optional metadata fields for state change events
+export type AgGridChartStateWithMetadata = Partial<AgGridChartState> & {
+  timestamp?: number;
+  hasChanges?: boolean;
+};
+
 export interface AgGridTableProps {
   gridTheme?: string;
   isDarkMode?: boolean;
@@ -80,6 +99,9 @@ export interface AgGridTableProps {
   cleanedTotals: DataRecord;
   showTotals: boolean;
   width: number;
+  onColumnStateChange?: (state: AgGridChartStateWithMetadata) => void;
+  gridRef?: RefObject<AgGridReact>;
+  chartState?: AgGridChartState;
 }
 
 ModuleRegistry.registerModules([AllCommunityModule, ClientSideRowModelModule]);
@@ -114,11 +136,14 @@ const AgGridDataTable: FunctionComponent<AgGridTableProps> = memo(
     cleanedTotals,
     showTotals,
     width,
+    onColumnStateChange,
+    chartState,
   }) => {
     const gridRef = useRef<AgGridReact>(null);
     const inputRef = useRef<HTMLInputElement>(null);
     const rowData = useMemo(() => data, [data]);
     const containerRef = useRef<HTMLDivElement>(null);
+    const lastCapturedStateRef = useRef<string | null>(null);
 
     const searchId = `search-${id}`;
     const gridInitialState: GridState = {
@@ -211,6 +236,34 @@ const AgGridDataTable: FunctionComponent<AgGridTableProps> = memo(
 
       if (!isSortable) return;
 
+      if (serverPagination && gridRef.current?.api && onColumnStateChange) {
+        const { api } = gridRef.current;
+
+        if (sortDir == null) {
+          api.applyColumnState({
+            defaultState: { sort: null },
+          });
+        } else {
+          api.applyColumnState({
+            defaultState: { sort: null },
+            state: [{ colId, sort: sortDir as 'asc' | 'desc', sortIndex: 0 }],
+          });
+        }
+
+        const columnState = api.getColumnState?.() || [];
+        const filterModel = api.getFilterModel?.() || {};
+        const sortModel = sortDir
+          ? [{ colId, sort: sortDir as 'asc' | 'desc', sortIndex: 0 }]
+          : [];
+
+        onColumnStateChange({
+          columnState,
+          sortModel,
+          filterModel,
+          timestamp: Date.now(),
+        });
+      }
+
       if (sortDir == null) {
         onSortChange([]);
         return;
@@ -234,6 +287,51 @@ const AgGridDataTable: FunctionComponent<AgGridTableProps> = memo(
       [serverPagination, gridInitialState, percentMetrics, onSortChange],
     );
 
+    const handleGridStateChange = useCallback(
+      debounce(() => {
+        if (onColumnStateChange && gridRef.current?.api) {
+          try {
+            const { api } = gridRef.current;
+
+            const columnState = api.getColumnState ? api.getColumnState() : [];
+
+            const filterModel = api.getFilterModel ? api.getFilterModel() : {};
+
+            const sortModel = columnState
+              .filter(col => col.sort)
+              .map(col => ({
+                colId: col.colId,
+                sort: col.sort as 'asc' | 'desc',
+                sortIndex: col.sortIndex || 0,
+              }))
+              .sort((a, b) => (a.sortIndex || 0) - (b.sortIndex || 0));
+
+            const stateToSave = {
+              columnState,
+              sortModel,
+              filterModel,
+              timestamp: Date.now(),
+            };
+
+            const stateHash = JSON.stringify({
+              columnOrder: columnState.map(c => c.colId),
+              sorts: sortModel,
+              filters: filterModel,
+            });
+
+            if (stateHash !== lastCapturedStateRef.current) {
+              lastCapturedStateRef.current = stateHash;
+
+              onColumnStateChange(stateToSave);
+            }
+          } catch (error) {
+            console.warn('Error capturing AG Grid state:', error);
+          }
+        }
+      }, Constants.SLOW_DEBOUNCE),
+      [onColumnStateChange],
+    );
+
     useEffect(() => {
       if (
         hasServerPageLengthChanged &&
@@ -257,6 +355,24 @@ const AgGridDataTable: FunctionComponent<AgGridTableProps> = memo(
     const onGridReady = (params: GridReadyEvent) => {
       // This will make columns fill the grid width
       params.api.sizeColumnsToFit();
+
+      // Restore saved AG Grid state from permalink if available
+      if (chartState && params.api) {
+        try {
+          if (chartState.columnState) {
+            params.api.applyColumnState?.({
+              state: chartState.columnState as ColumnState[],
+              applyOrder: true,
+            });
+          }
+
+          if (chartState.filterModel) {
+            params.api.setFilterModel?.(chartState.filterModel);
+          }
+        } catch {
+          // Silently fail if state restoration fails
+        }
+      }
     };
 
     return (
@@ -313,7 +429,9 @@ const AgGridDataTable: FunctionComponent<AgGridTableProps> = memo(
           rowSelection="multiple"
           animateRows
           onCellClicked={handleCrossFilter}
+          onStateUpdated={handleGridStateChange}
           initialState={gridInitialState}
+          maintainColumnOrder
           suppressAggFuncInHeader
           enableCellTextSelection
           quickFilterText={serverPagination ? '' : quickFilterText}