superset2/CONTROL_PANEL_MODERNIZATION.md

Control Panel Modernization Guide

Current State

Apache Superset's control panels currently use a legacy controlSetRows structure that relies on nested arrays to define layout. This approach has several limitations:

1. Rigid Layout: The nested array structure makes it difficult to create responsive or complex layouts
2. Poor Type Safety: Arrays of arrays don't provide good TypeScript support
3. Mixed Paradigms: String references, configuration objects, and React components are mixed together
4. Limited Reusability: Layout logic is embedded in the structure rather than using composable components

Migration Strategy

Phase 1: Component Modernization ✅ COMPLETED

• Replaced string-based control references with React components
• Updated individual control components to use Ant Design
• Modernized the ControlRow component to use Ant Design's Grid

Phase 2: Layout Utilities ✅ COMPLETED

• Created ControlPanelLayout.tsx with reusable layout components
• Implemented ControlSection, SingleControlRow, TwoColumnRow, ThreeColumnRow
• Updated control group components to use Ant Design Row/Col

Phase 3: React-Based Control Panels 🚧 IN PROGRESS

• Create ReactControlPanel component for rendering modern panels
• Support both legacy and modern formats during transition
• Provide migration helpers and examples

Phase 4: Gradual Migration 📋 TODO

• Migrate chart control panels one by one
• Start with simpler charts (Pie, Bar) before complex ones
• Maintain backward compatibility throughout

Modern Control Panel Structure

Legacy Structure (controlSetRows)

const config: ControlPanelConfig = {
  controlPanelSections: [
    {
      label: t('Query'),
      expanded: true,
      controlSetRows: [
        [GroupByControl()],
        [MetricControl()],
        [AdhocFiltersControl()],
        [RowLimitControl()],
      ],
    },
  ],
};

Modern Structure (React Components)

const modernConfig: ReactControlPanelConfig = {
  sections: [
    {
      key: 'query',
      label: t('Query'),
      expanded: true,
      render: ({ values, onChange }) => (
        <>
          <SingleControlRow>
            <GroupByControl value={values.groupby} onChange={onChange} />
          </SingleControlRow>
          <SingleControlRow>
            <MetricControl value={values.metrics} onChange={onChange} />
          </SingleControlRow>
          <TwoColumnRow
            left={<AdhocFiltersControl value={values.adhoc_filters} onChange={onChange} />}
            right={<RowLimitControl value={values.row_limit} onChange={onChange} />}
          />
        </>
      ),
    },
  ],
};

Benefits of Modernization

1. Better Type Safety: Full TypeScript support with proper interfaces
2. Flexible Layouts: Use Ant Design's Grid system for responsive layouts
3. Cleaner Code: React components instead of nested arrays
4. Improved DX: Better IDE support and autocomplete
5. Easier Testing: Component-based architecture is easier to test
6. Consistent Styling: Leverage Ant Design's theme system

Migration Example

To migrate a control panel:

1. Create a modern version alongside the existing one:

   // controlPanelModern.tsx
   export const modernConfig: ReactControlPanelConfig = {
     sections: [/* ... */]
   };
   

2. Use the compatibility wrapper for backward compatibility:

   export default createReactControlPanel(modernConfig);
   

3. Update the chart plugin to use the new control panel:

   import controlPanel from './controlPanelModern';
   

Layout Components Available

• ControlSection: Collapsible section container
• SingleControlRow: Full-width single control
• TwoColumnRow: Two controls side by side (50/50)
• ThreeColumnRow: Three controls in a row (33/33/33)
• Row and Col from Ant Design for custom layouts

Files Created

1. packages/superset-ui-chart-controls/src/shared-controls/components/ControlPanelLayout.tsx

   • Layout utility components

2. packages/superset-ui-chart-controls/src/shared-controls/components/ModernControlPanelExample.tsx

   • Example of modern control panel structure

3. plugins/plugin-chart-echarts/src/Pie/controlPanelModern.tsx

   • Modern version of Pie chart control panel

Next Steps

1. Complete the ReactControlPanel integration with ControlPanelsContainer
2. Create migration tooling to help convert existing panels
3. Document best practices for control panel design
4. Update chart plugin template to use modern structure
5. Gradually migrate all 90+ control panels in the codebase

Technical Debt Addressed

• Eliminates nested array layout structure
• Removes string-based control references
• Reduces coupling between layout and configuration
• Improves maintainability and testability
• Enables better code splitting and lazy loading

Backward Compatibility

The migration maintains full backward compatibility:

• Existing control panels continue to work
• Both formats can coexist during migration
• No breaking changes to the public API
• Charts can be migrated incrementally