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

word-cloud-component.mddocs/

Word Cloud Component

React component for rendering interactive word cloud visualizations with configurable encoding channels and rotation options using D3.js.

Capabilities

WordCloud Component

Main React component that renders SVG-based word cloud visualizations.

/**
 * Word cloud visualization component using D3.js for layout calculation
 * Renders words with configurable size, color, font, and rotation
 */
class WordCloud extends React.PureComponent<WordCloudProps, WordCloudState> {
  constructor(props: FullWordCloudProps);
  componentDidMount(): void;
  componentDidUpdate(prevProps: WordCloudProps): void;
  componentWillUnmount(): void;
  render(): React.ReactElement;
}

interface WordCloudProps extends WordCloudVisualProps {
  data: PlainObject[];
  height: number;
  width: number;
  sliceId: number;
}

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

interface WordCloudState {
  words: Word[];
  scaleFactor: number;
}

Usage Example:

import WordCloud from '@superset-ui/plugin-chart-word-cloud';

<WordCloud
  data={[
    { text: 'analytics', count: 100, category: 'tech' },
    { text: 'visualization', count: 85, category: 'design' },
    { text: 'dashboard', count: 70, category: 'tech' }
  ]}
  width={600}
  height={400}
  sliceId={1}
  encoding={{
    text: { field: 'text' },
    fontSize: { field: 'count', type: 'quantitative', scale: { range: [10, 60] } },
    color: { field: 'category', type: 'nominal' }
  }}
  rotation="random"
/>

Visual Encoding System

Configurable encoding channels for mapping data to visual properties.

interface WordCloudEncoding {
  color: ColorEncoding;
  fontFamily: CategoryEncoding<string>;
  fontSize: NumericEncoding;
  fontWeight: CategoryEncoding<string | number>;
  text: TextEncoding;
}

type WordCloudEncodingConfig = {
  color: ['Color', string];
  fontFamily: ['Category', string];
  fontSize: ['Numeric', number];
  fontWeight: ['Category', string | number];
  text: ['Text', string];
};

Encoding Channels:

  • text: Maps data field to displayed word text
  • fontSize: Maps numeric data to font size (quantitative scale)
  • color: Maps data to color (categorical or sequential scales)
  • fontFamily: Maps data to font family selection
  • fontWeight: Maps data to font weight (normal, bold, etc.)

Usage Example:

const encoding: Partial<WordCloudEncoding> = {
  text: { field: 'word' },
  fontSize: {
    field: 'frequency',
    type: 'quantitative',
    scale: { range: [12, 72], zero: true }
  },
  color: {
    field: 'sentiment',
    type: 'nominal',
    scale: { scheme: 'category10' }
  },
  fontWeight: { value: 'bold' }
};

Rotation Options

Configurable word rotation patterns for layout variety.

type RotationType = 'flat' | 'random' | 'square';

const ROTATION: Record<RotationType, () => number> = {
  flat: () => 0;
  random: () => number; // Random rotation between -90° and 90°
  square: () => number; // 0° or 90° rotation
};

Rotation Types:

  • flat: All words horizontal (0 degrees)
  • random: Random rotation between -90 and 90 degrees in 30-degree increments
  • square: Either horizontal (0°) or vertical (90°)

Layout Algorithm

D3.js cloud layout integration with automatic scaling and collision detection.

/**
 * Internal layout generation with automatic scaling
 * Ensures top percentage of results are always visible
 */
interface LayoutConstants {
  SCALE_FACTOR_STEP: 0.5;
  MAX_SCALE_FACTOR: 3;
  TOP_RESULTS_PERCENTAGE: 0.1;
}

Layout Features:

  • Automatic collision detection and word placement
  • Adaptive scaling to ensure important words are always visible
  • Configurable padding between words (5px default)
  • Lazy evaluation with callback-based completion
  • Priority system ensuring top 10% of results are always displayed

Internal Methods:

/**
 * Updates word cloud when data or encoding changes
 */
update(): void;

/**
 * Generates word cloud layout using d3-cloud
 * @param encoder - Configured encoder for visual mappings
 * @param scaleFactor - Current scale factor for fitting
 * @param isValid - Validation function for layout completeness
 */
generateCloud(
  encoder: Encoder<WordCloudEncodingConfig>,
  scaleFactor: number,
  isValid: (words: Word[]) => boolean
): void;

/**
 * Updates component state with computed word positions
 * @param words - Array of positioned words from d3-cloud
 */
setWords(words: Word[]): void;

D3.js Integration

The component uses d3-cloud for word positioning and d3-scale for data mapping:

// Word interface from d3-cloud
interface Word {
  text: string;
  size: number;
  x: number;
  y: number;
  rotate: number;
  font: string;
  weight: string | number;
}

Cloud Layout Configuration:

  • Size: [width * scaleFactor, height * scaleFactor]
  • Padding: 5 pixels between words
  • Text accessor: Uses encoding channel for text field
  • Font accessor: Uses encoding channel for font family
  • Font size accessor: Uses encoding channel for size calculation
  • Rotation accessor: Uses selected rotation function

Default Configuration

const defaultProps: Required<WordCloudVisualProps> = {
  encoding: {},
  rotation: 'flat'
};

const defaultEncoding = {
  color: { value: 'black' },
  fontFamily: { value: 'sans-serif' },
  fontSize: { value: 20 },
  fontWeight: { value: 'bold' },
  text: { value: '' }
};

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