CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-superset-ui--plugin-chart-word-cloud

A comprehensive word cloud chart plugin for Apache Superset that creates interactive visualizations from text frequency data

—

Pending
Overview
Eval results
Files

data-transformation.mddocs/

Data Transformation

Transform functions that convert Superset chart properties into word cloud component properties, handling both modern and legacy form data formats.

Capabilities

Modern Transform Props

Transforms ChartProps to WordCloudProps for the modern plugin implementation.

/**
 * Transform function for modern WordCloudChartPlugin
 * Extracts relevant properties from Superset chart props
 * @param chartProps - Standard Superset chart properties
 * @returns WordCloud component properties
 */
function transformProps(chartProps: ChartProps): WordCloudProps;

interface ChartProps {
  width: number;
  height: number;
  formData: WordCloudFormData;
  queriesData: Array<{ data: PlainObject[] }>;
}

Usage Example:

import { WordCloudTransformProps } from '@superset-ui/plugin-chart-word-cloud';

const chartProps = {
  width: 600,
  height: 400,
  formData: {
    series: 'word_column',
    metric: 'frequency',
    encoding: {
      fontSize: { field: 'frequency', type: 'quantitative' },
      text: { field: 'word_column' }
    },
    rotation: 'random',
    sliceId: 123
  },
  queriesData: [{
    data: [
      { word_column: 'analytics', frequency: 100 },
      { word_column: 'dashboard', frequency: 85 }
    ]
  }]
};

const wordCloudProps = WordCloudTransformProps(chartProps);
// Returns: { data, encoding, height, rotation, width, sliceId }

Legacy Transform Props

Transforms ChartProps to WordCloudProps for the legacy plugin implementation with automatic encoding generation.

/**
 * Transform function for LegacyWordCloudChartPlugin
 * Converts legacy form data format into modern encoding structure
 * @param chartProps - Standard Superset chart properties with legacy form data
 * @returns WordCloud component properties with converted encoding
 */
function transformProps(chartProps: ChartProps): WordCloudProps;

Legacy Form Data Conversion:

The legacy transform automatically converts old-style form data into the modern encoding format:

// Legacy form data input
const legacyFormData = {
  series: 'word_field',
  metric: 'count_field',
  colorScheme: 'category10',
  sizeFrom: 10,
  sizeTo: 80,
  rotation: 'square'
};

// Automatically converted to modern encoding
const modernEncoding = {
  color: {
    field: 'word_field',
    scale: { scheme: 'category10' },
    type: 'nominal'
  },
  fontSize: {
    field: 'count_field',
    scale: { range: [10, 80], zero: true },
    type: 'quantitative'
  },
  text: {
    field: 'word_field'
  }
};

Metric Label Extraction

Helper function for extracting metric labels from various legacy metric formats.

/**
 * Extracts metric label from legacy metric configuration
 * Handles string, array, and object metric formats
 * @param metric - Legacy metric configuration in various formats
 * @returns Extracted metric label or undefined
 */
function getMetricLabel(
  metric: string | undefined | Array<any> | { label: string }
): string | undefined;

Metric Format Support:

// String format
getMetricLabel('sum_sales') // Returns: 'sum_sales'

// Object format with label
getMetricLabel({ label: 'Total Sales', column: 'sales' }) // Returns: 'Total Sales'

// Array format (uses first element)
getMetricLabel([
  { label: 'Primary Metric', column: 'metric1' },
  { label: 'Secondary Metric', column: 'metric2' }
]) // Returns: 'Primary Metric'

// Undefined/empty
getMetricLabel(undefined) // Returns: undefined
getMetricLabel([]) // Returns: undefined

Form Data Types

Modern Form Data

interface WordCloudFormData extends QueryFormData, WordCloudVisualProps {
  series: string; // Field name for word text
}

interface WordCloudVisualProps {
  encoding?: Partial<WordCloudEncoding>;
  rotation?: RotationType;
}

Properties:

  • series: Data field containing the text to display as words
  • encoding: Visual encoding configuration for size, color, etc.
  • rotation: Word rotation pattern ('flat', 'random', 'square')
  • Plus all QueryFormData properties: metrics, filters, time range, etc.

Legacy Form Data

interface LegacyWordCloudFormData extends QueryFormData {
  colorScheme: string;        // Color scheme name (e.g., 'category10')
  rotation?: RotationType;    // Word rotation pattern
  series: string;             // Field name for word text
  sizeFrom?: number;          // Minimum font size (default: varies)
  sizeTo: number;             // Maximum font size
}

Properties:

  • colorScheme: Named color scheme for categorical coloring
  • series: Data field for both text and color grouping
  • sizeFrom/sizeTo: Font size range for frequency mapping
  • rotation: Word rotation pattern
  • Plus all QueryFormData properties: metrics, filters, time range, etc.

Transformation Process

Modern Plugin Flow

  1. Extract encoding, rotation, sliceId from formData
  2. Get chart dimensions (width, height)
  3. Extract data array from first query result
  4. Return object with all properties for WordCloud component

Legacy Plugin Flow

  1. Extract legacy properties: colorScheme, metric, rotation, series, sizeFrom, sizeTo, sliceId
  2. Use getMetricLabel() to extract metric field name
  3. Build modern encoding object:
    • Color encoding using series field and color scheme
    • Font size encoding using metric field and size range
    • Text encoding using series field
  4. Get chart dimensions and data
  5. Return object with converted properties for WordCloud component

Error Handling

The transform functions handle various edge cases:

  • Missing metric: FontSize encoding is set to undefined if no metric label can be extracted
  • Invalid data: Empty arrays are handled gracefully
  • Missing properties: Default values are used for optional properties
  • Type safety: All transforms maintain TypeScript type safety throughout the conversion process

Install with Tessl CLI

npx tessl i tessl/npm-superset-ui--plugin-chart-word-cloud

docs

control-panel.md

data-transformation.md

encodable-configuration.md

index.md

plugin-classes.md

word-cloud-component.md

tile.json