tessl/npm-superset-ui--core

Core utilities and components for Apache Superset's frontend UI framework providing data visualization, formatting, and chart composition capabilities

—

Pending

Overview

Eval results

Files

Dashboard Components

Name: tessl/npm-superset-ui--core
Author: tessl

This module provides comprehensive type definitions and utilities for dashboard functionality within Superset applications. It focuses on native filters, data masks, filter sets, and dashboard component metadata that enable interactive filtering and cross-filter capabilities across dashboard charts.

Overview

The dashboard module defines the core types and interfaces that power Superset's dashboard filtering system. It supports native filters (dashboard-level filters), cross-filters (chart-to-chart filtering), filter sets (saved filter configurations), and the data mask system that applies filters to charts.

Core Filter Types

Filter Structure { .api }

Core filter definition that represents a native dashboard filter:

import { Filter, Divider, NativeFilterType } from '@superset-ui/core';

interface Filter {
  // Identity and metadata
  id: string;                    // Randomly generated unique identifier
  name: string;                  // Display name for the filter
  description: string;           // User-friendly description
  type: typeof NativeFilterType.NATIVE_FILTER;
  
  // Filter configuration
  filterType: string;            // Type of filter component (select, time, etc.)
  controlValues: { [key: string]: any }; // Filter-specific configuration
  
  // Target configuration
  targets: [Partial<NativeFilterTarget>]; // Currently single target, array for future multi-target support
  scope: NativeFilterScope;      // Which charts this filter applies to
  
  // Cascade and dependencies
  cascadeParentIds: string[];    // Parent filters for cascading behavior
  defaultDataMask: DataMask;     // Default filter state
  
  // Time-specific properties (for time filters)
  sortMetric?: string | null;
  adhoc_filters?: AdhocFilter[];
  granularity_sqla?: string;
  granularity?: string;
  druid_time_origin?: string;
  time_grain_sqla?: string;
  time_range?: string;
  
  // Behavior configuration
  requiredFirst?: boolean;       // Must be set before other filters
  tabsInScope?: string[];        // Dashboard tabs this filter applies to
  chartsInScope?: number[];      // Specific charts this filter applies to
}

// Divider for organizing filters in the filter panel
interface Divider extends Partial<Omit<Filter, 'id' | 'type'>> {
  id: string;
  title: string;
  description: string;
  type: typeof NativeFilterType.DIVIDER;
}

enum NativeFilterType {
  NATIVE_FILTER = 'NATIVE_FILTER',
  DIVIDER = 'DIVIDER'
}

Filter Target System { .api }

System for defining what data sources and columns filters operate on:

interface NativeFilterTarget {
  datasetId: number;             // ID of the dataset being filtered
  column: NativeFilterColumn;    // Column being filtered
}

interface NativeFilterColumn {
  name: string;                  // Column name in the dataset
  displayName?: string;          // Human-readable column name
}

interface NativeFilterScope {
  rootPath: string[];            // Path to scope root in dashboard component tree
  excluded: number[];            // Chart IDs excluded from filter scope
}

Data Mask System

DataMask Interface { .api }

The data mask system applies filter values to charts and tracks filter state:

interface DataMask {
  extraFormData?: QueryFormData;    // Additional query parameters from filter
  filterState?: {                   // Current filter state
    value?: any;                    // Filter value (selected items, date range, etc.)
    label?: string;                 // Display label for current selection
  };
  ownState?: {                      // Filter component internal state
    coltypes?: string[];            // Column data types
    [key: string]: any;
  };
}

// Data mask types for different filter sources
enum DataMaskType {
  NativeFilters = 'nativeFilters', // Dashboard-level native filters
  CrossFilters = 'crossFilters'    // Chart-to-chart cross filters
}

// Data mask state management
type DataMaskState = { [id: string]: DataMask };

type DataMaskWithId = { id: string } & DataMask;
type DataMaskStateWithId = { [filterId: string]: DataMaskWithId };

Filter Collections and Sets

Filter Organization { .api }

Types for organizing and managing collections of filters:

// Collection of all filters in a dashboard
type Filters = {
  [filterId: string]: Filter | Divider;
};

// Array configuration format for filter ordering
type FilterConfiguration = Array<Filter | Divider>;

// Saved filter sets for quick filter application
interface FilterSet {
  id: number;                       // Unique identifier for the filter set
  name: string;                     // Display name
  nativeFilters: Filters;           // Filter configurations in this set
  dataMask: DataMaskStateWithId;    // Saved filter values and state
}

type FilterSets = {
  [filtersSetId: string]: FilterSet;
};

Dashboard State Management

Native Filters State { .api }

Complete state structure for dashboard native filters:

interface NativeFiltersState {
  filters: Filters;                 // All filter definitions
  filterSets: FilterSets;          // Saved filter sets
  focusedFilterId?: string;        // Currently focused filter in config
}

interface DashboardComponentMetadata {
  nativeFilters: NativeFiltersState;  // Native filter state
  dataMask: DataMaskStateWithId;      // Applied data masks
}

Type Guards and Utilities

Filter Type Detection { .api }

Utility functions for working with filter objects:

// Type guard to check if filter element is a native filter
function isNativeFilter(filterElement: Filter | Divider): filterElement is Filter;

// Type guard to check if filter element is a divider
function isFilterDivider(filterElement: Filter | Divider): filterElement is Divider;

Usage Examples

Creating Native Filters

import { 
  Filter, 
  NativeFilterType, 
  NativeFilterScope, 
  DataMask 
} from '@superset-ui/core';

// Create a select filter for a category column
const categoryFilter: Filter = {
  id: 'filter_category_001',
  name: 'Product Category',
  description: 'Filter charts by product category',
  type: NativeFilterType.NATIVE_FILTER,
  filterType: 'filter_select',
  
  // Target the 'category' column in dataset 5
  targets: [{
    datasetId: 5,
    column: {
      name: 'category',
      displayName: 'Product Category'
    }
  }],
  
  // Apply to all charts except chart 10
  scope: {
    rootPath: ['ROOT_ID'],
    excluded: [10]
  },
  
  // No parent filters
  cascadeParentIds: [],
  
  // Default to no selection
  defaultDataMask: {
    filterState: {
      value: null,
      label: 'All Categories'
    }
  },
  
  controlValues: {
    enableEmptyFilter: true,
    defaultToFirstItem: false,
    multiSelect: true,
    searchAllOptions: false,
    inverseSelection: false
  }
};

// Create a time range filter
const timeFilter: Filter = {
  id: 'filter_time_001',
  name: 'Time Range',
  description: 'Select date range for analysis',
  type: NativeFilterType.NATIVE_FILTER,
  filterType: 'filter_timerange',
  
  targets: [{
    datasetId: 5,
    column: {
      name: 'created_at',
      displayName: 'Creation Date'
    }
  }],
  
  scope: {
    rootPath: ['ROOT_ID'],
    excluded: []
  },
  
  cascadeParentIds: [],
  
  defaultDataMask: {
    filterState: {
      value: 'Last 30 days'
    }
  },
  
  controlValues: {
    defaultValue: 'Last 30 days'
  },
  
  // Time-specific configuration
  time_range: 'Last 30 days',
  granularity_sqla: 'created_at'
};

Managing Filter Sets

import { FilterSet, DataMaskStateWithId } from '@superset-ui/core';

// Create a saved filter set
const quarterlyReportFilters: FilterSet = {
  id: 1,
  name: 'Q1 2024 Report',
  nativeFilters: {
    'filter_time_001': timeFilter,
    'filter_category_001': categoryFilter
  },
  dataMask: {
    'filter_time_001': {
      id: 'filter_time_001',
      filterState: {
        value: '2024-01-01 : 2024-03-31'
      }
    },
    'filter_category_001': {
      id: 'filter_category_001',
      filterState: {
        value: ['Electronics', 'Clothing'],
        label: 'Electronics, Clothing'
      }
    }
  }
};

// Apply filter set to dashboard
const applyFilterSet = (filterSet: FilterSet): DataMaskStateWithId => {
  return filterSet.dataMask;
};

Filter Scope Management

import { NativeFilterScope, isNativeFilter } from '@superset-ui/core';

// Create scope that applies to specific charts only
const restrictedScope: NativeFilterScope = {
  rootPath: ['ROOT_ID'],
  excluded: [] // Empty means include all charts in scope
};

// Create scope that excludes specific charts
const excludedScope: NativeFilterScope = {
  rootPath: ['ROOT_ID', 'TAB_001'], // Apply only to specific tab
  excluded: [15, 20, 25] // Exclude these chart IDs
};

// Check which charts are in scope
const getChartsInScope = (
  scope: NativeFilterScope, 
  allChartIds: number[]
): number[] => {
  return allChartIds.filter(id => !scope.excluded.includes(id));
};

Cross-Filter Integration

import { DataMask, DataMaskType } from '@superset-ui/core';

// Handle cross-filter from chart interaction
const handleChartCrossFilter = (
  chartId: number,
  filterColumn: string,
  filterValues: any[]
): DataMask => {
  return {
    extraFormData: {
      filters: [{
        col: filterColumn,
        op: 'IN',
        val: filterValues
      }]
    },
    filterState: {
      value: filterValues,
      label: `${filterValues.length} selected`
    }
  };
};

// Apply cross-filter to dashboard state
const applyCrossFilter = (
  currentDataMask: DataMaskStateWithId,
  sourceChartId: number,
  targetFilter: DataMask
): DataMaskStateWithId => {
  return {
    ...currentDataMask,
    [`cross_filter_${sourceChartId}`]: {
      id: `cross_filter_${sourceChartId}`,
      ...targetFilter
    }
  };
};

Cascading Filter Implementation

import { Filter } from '@superset-ui/core';

// Create cascading filters (country -> state -> city)
const countryFilter: Filter = {
  id: 'filter_country',
  name: 'Country',
  type: NativeFilterType.NATIVE_FILTER,
  filterType: 'filter_select',
  cascadeParentIds: [],
  // ... other properties
} as Filter;

const stateFilter: Filter = {
  id: 'filter_state',
  name: 'State/Province',
  type: NativeFilterType.NATIVE_FILTER,
  filterType: 'filter_select',
  cascadeParentIds: ['filter_country'], // Depends on country filter
  // ... other properties
} as Filter;

const cityFilter: Filter = {
  id: 'filter_city',
  name: 'City',
  type: NativeFilterType.NATIVE_FILTER,
  filterType: 'filter_select',
  cascadeParentIds: ['filter_country', 'filter_state'], // Depends on both
  // ... other properties
} as Filter;

// Process cascade dependencies
const processCascadeUpdate = (
  filters: Filter[],
  updatedFilterId: string,
  newValue: any
): DataMaskStateWithId => {
  const updatedMasks: DataMaskStateWithId = {};
  
  // Find child filters that depend on the updated filter
  const childFilters = filters.filter(f => 
    f.cascadeParentIds.includes(updatedFilterId)
  );
  
  // Reset child filters when parent changes
  childFilters.forEach(child => {
    updatedMasks[child.id] = {
      id: child.id,
      filterState: {
        value: null,
        label: 'All'
      }
    };
  });
  
  return updatedMasks;
};

Filter Organization with Dividers

import { Divider, NativeFilterType, FilterConfiguration } from '@superset-ui/core';

// Create filter dividers for organization
const timeDivider: Divider = {
  id: 'divider_time',
  title: 'Time Filters',
  description: 'Date and time-based filtering options',
  type: NativeFilterType.DIVIDER
};

const categoryDivider: Divider = {
  id: 'divider_categories',
  title: 'Category Filters', 
  description: 'Product and business category filters',
  type: NativeFilterType.DIVIDER
};

// Organize filters with dividers
const filterConfiguration: FilterConfiguration = [
  timeDivider,
  timeFilter,
  categoryDivider,
  categoryFilter,
  productFilter
];

// Process filter configuration
const organizeFilters = (config: FilterConfiguration) => {
  const filters: Filter[] = [];
  const dividers: Divider[] = [];
  
  config.forEach(item => {
    if (isNativeFilter(item)) {
      filters.push(item);
    } else if (isFilterDivider(item)) {
      dividers.push(item);
    }
  });
  
  return { filters, dividers };
};

tessl/npm-superset-ui--core

dashboard.mddocs/

Dashboard Components

Overview

Core Filter Types

Filter Structure { .api }

Filter Target System { .api }

Data Mask System

DataMask Interface { .api }

Filter Collections and Sets

Filter Organization { .api }

Dashboard State Management

Native Filters State { .api }

Type Guards and Utilities

Filter Type Detection { .api }

Usage Examples

Creating Native Filters

Managing Filter Sets

Filter Scope Management

Cross-Filter Integration

Cascading Filter Implementation

Filter Organization with Dividers

Related Documentation

tessl/npm-superset-ui--core

dashboard.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Dashboard Components

Overview

Core Filter Types

Filter Structure { .api }

Filter Target System { .api }

Data Mask System

DataMask Interface { .api }

Filter Collections and Sets

Filter Organization { .api }

Dashboard State Management

Native Filters State { .api }

Type Guards and Utilities

Filter Type Detection { .api }

Usage Examples

Creating Native Filters

Managing Filter Sets

Filter Scope Management

Cross-Filter Integration

Cascading Filter Implementation

Filter Organization with Dividers

Related Documentation

dashboard.mddocs/