Developing a Custom chart

custom-chart-builder/
├── custom-chart-build-output/  # Production build files
├── projects/
│   ├── builder/                # Angular application for the chart builder UI
│   └── custom-chart/           # Your custom chart implementation
│       └── src/
│           ├── chart.ts        # Main chart rendering logic
│           ├── chart.css       # Chart styles
│           ├── manifest.json   # Chart configuration and slot definitions
│           ├── icon.svg        # Chart icon
│           └── index.ts        # Entry point

export { render, resize, buildQuery } from './chart';

{
  "slots": [
    {
      "name": "category",
      "rotate": false,
      "label": "Category",
      "type": "categorical",
      "order": 1,
      "options": {
        "isBinningDisabled": true,
        "areDatetimeOptionsEnabled": true
      },
      "isRequired": true,
      "position": "bottom"
    },
    {
      "name": "measure",
      "rotate": true,
      "label": "Value",
      "type": "numeric",
      "order": 2,
      "options": {
        "isAggregationDisabled": false
      },
      "isRequired": true,
      "position": "middle"
    },
    {
      "name": "legend",
      "rotate": false,
      "label": "Legend",
      "type": "categorical",
      "order": 3,
      "options": {
        "isBinningDisabled": true
      },
      "isRequired": false,
      "position": "right"
    }
  ]
}

npm run validate

[
  { id: 'belgium', name: { en: 'Belgium' }, color: '#4f46e5' }, // category dimension
  { id: 'enterprise', name: { en: 'Enterprise' } },             // legend dimension
  12450                                                        // measure
]

// Import required types
import type { ItemData, Slot, SlotConfig, ThemeConfig } from '@luzmo/dashboard-contents-types';
import * as d3 from 'd3';

interface ChartParams {
  container: HTMLElement;           // The DOM element where your chart will be rendered
  data: ItemData['data'];           // The data rows from the server
  slots: Slot[];                    // The filled slots with column mappings
  slotConfigurations: SlotConfig[]; // The configuration of available slots
  options: Record<string, any> & { theme?: ThemeConfig }; // Additional options passed to the chart
  language: string;                 // Current language code (e.g., 'en')
  dimensions: {                     // Width and height of the chart container in pixels
    width: number;
    height: number;
  };
}

// Render function implementation
export function render({
  container,
  data = [],
  slots = [],
  slotConfigurations = [],
  options = {},
  language = 'en',
  dimensions: { width = 600, height = 400 } = {}
}: ChartParams): void {
  // 1. Clear the container
  container.innerHTML = '';

  // 2. Check if data exists
  const rows = data ?? [];
  const hasData = rows.length > 0;

  if (!hasData) {
    container.textContent = 'Add data to preview this chart.';
    return;
  }

  // 3. Extract and process data
  const chartData = rows.map(row => {
    const rawCategory = row[0];
    let categoryValue: unknown = rawCategory ?? 'Unknown';

    if (typeof rawCategory === 'object' && rawCategory !== null && 'name' in rawCategory) {
      const categoryObject = rawCategory as { name?: string | Record<string, string>; id?: string };
      categoryValue =
        typeof categoryObject.name === 'object' && categoryObject.name !== null
          ? categoryObject.name[language] ?? categoryObject.name.en ?? Object.values(categoryObject.name)[0]
          : categoryObject.name ?? categoryObject.id ?? 'Unknown';
    }

    return {
      category: String(categoryValue),
      value: Number(row[1] ?? 0)
    };
  });

  // 4. Create visualization (SVG, Canvas, etc.)
  const svg = d3.select(container)
    .append('svg')
    .attr('width', width)
    .attr('height', height);

  // 5. Add your chart elements here...

  // 6. Store state for resize
  (container as any).__chartData = chartData;
}

export function resize({
  container,
  slots = [],
  slotConfigurations = [],
  options = {},
  language = 'en',
  dimensions: { width = 600, height = 400 } = {}
}: ChartParams): void {
  const chartData = (container as any).__chartData ?? [];

  const svg = d3.select(container)
    .select<SVGSVGElement>('svg')
    .attr('width', width)
    .attr('height', height);

  // Update scales, axes, and marks using chartData and the new dimensions.
  // If your chart is simpler, you can also call a shared updateChart(svg, chartData, dimensions) helper.
}

import type {
  ItemQuery,
  ItemQueryDimension,
  ItemQueryMeasure,
  Slot,
  SlotConfig
} from '@luzmo/dashboard-contents-types';

interface BuildQueryParams {
  slots: Slot[];
  slotConfigurations: SlotConfig[];
}

export function buildQuery({
  slots = [],
  slotConfigurations = []
}: BuildQueryParams): ItemQuery {
  const dimensions: ItemQueryDimension[] = [];
  const measures: ItemQueryMeasure[] = [];
  
  // Extract category dimension
  const categorySlot = slots.find(slot => slot.name === 'category');
  const categoryContent = categorySlot?.content;

  if (categoryContent?.length > 0) {
    const [category] = categoryContent;
    dimensions.push({
      dataset_id: category.datasetId,
      column_id: category.columnId,
      level: category.level || 1
    });
  }

  // Extract measure
  const measureSlot = slots.find(slot => slot.name === 'measure');
  const measureContent = measureSlot?.content;

  if (measureContent?.length > 0) {
    const [measure] = measureContent;

    // Handle different types of measures
    if (measure.aggregationFunc && ['sum', 'average', 'min', 'max', 'count'].includes(measure.aggregationFunc)) {
      measures.push({
        dataset_id: measure.datasetId,
        column_id: measure.columnId,
        aggregation: { type: measure.aggregationFunc }
      });
    }
    else {
      measures.push({
        dataset_id: measure.datasetId,
        column_id: measure.columnId
      });
    }
  }

  // Add ordering by category, if category slot is filled.
  const order: ItemQuery['order'] = categoryContent?.[0]
    ? [{
        dataset_id: categoryContent[0].datasetId,
        column_id: categoryContent[0].columnId,
        order: 'asc'
      }]
    : [];
  
  // Add default limit of 10000 rows for performance reasons.
  const limit = { by: 10000, offset: 0 };

  const query: ItemQuery = {
    dimensions,
    measures,
    order,
    limit
  };

  return query;
}

import { formatter } from '@luzmo/analytics-components-kit/utils';

import { formatter } from '@luzmo/analytics-components-kit/utils';

export function render({ data, slots }: ChartParams): void {
  const rows = data ?? [];
  const categorySlot = slots.find(slot => slot.name === 'category');
  const measureSlot = slots.find(slot => slot.name === 'measure');
  const categoryContent = categorySlot?.content?.[0];
  const measureContent = measureSlot?.content?.[0];

  const measureFormatter = measureContent
    ? formatter(measureContent)
    : (val: any) => String(val);

  const categoryFormatter = categoryContent
    ? formatter(categoryContent, { level: categoryContent.level })
    : (val: any) => String(val);

  const formattedData = rows.map(row => {
    const rawCategoryValue =
      typeof row[0] === 'object' && row[0] !== null && 'name' in row[0]
        ? (row[0] as { name?: string | Record<string, string> }).name
        : row[0] ?? 'Unknown';
    const rawCategory =
      typeof rawCategoryValue === 'object' && rawCategoryValue !== null
        ? (rawCategoryValue as Record<string, string>).en ?? Object.values(rawCategoryValue)[0]
        : rawCategoryValue;

    return {
      category: categoryFormatter(
        categoryContent?.type === 'datetime'
          ? new Date(String(rawCategory))
          : typeof rawCategory === 'number' || rawCategory instanceof Date
            ? rawCategory
            : String(rawCategory ?? '')
      ),
      value: measureFormatter(row[1] as number | string | Date)
    };
  });
}

interface ThemeConfig {
  axis?: Record<'fontSize', number> // Font size of the axis labels.
  background?: string; // Background color of the dashboard canvas.
  borders?: {
    'border-color'?: string; // Color of the border
    'border-radius'?: string; // Radius of the border
    'border-style'?: string; // Style of the border
    'border-top-width'?: string; // Top width of the border
    'border-right-width'?: string; // Right width of the border
    'border-bottom-width'?: string; // Bottom width of the border
    'border-left-width'?: string; // Left width of the border
  }; // Border styling.
  boxShadow?: {
    size?: 'S' | 'M' | 'L' | 'none'; // Size of the boxshadow.
    color?: string; // Color of the boxshadow.
  }; // Box shadow styling.
  colors?: string[]; // Custom color palette, an array of colors used when a chart needs multiple colors (e.g. donut chart).
  font?: {
    fontFamily?: string; // Font family used in the chart.
    fontSize?: number; // Font size in px.
    'font-weight'?: number; // Font weight.
    'font-style'?: 'normal'; // Font style.
  }; // Font styling.
  itemsBackground?: string; // Background color of the chart.
  itemSpecific?: {
    rounding?: number; // Rounding of elements in the chart.
    padding?: number; // Padding between elements in the chart.
  };
  legend?: {
    type?: 'normal' | 'line' | 'circle'; // Display type of the legend.
    fontSize?: number; // Font size of the legend in px.
    lineHeight?: number; // Line height of the legend in px.
  }; // Legend styling, applied if a legend is displayed.
  mainColor?: string; // Main color of the theme.
  title?: {
    align?: 'left' | 'center' | 'right'; // Alignment of the title
    bold?: boolean; // Whether the title is bold
    border?: boolean; // Whether the title has a bottom border
    fontSize?: number; // Font size of the title in px
    italic?: boolean; // Whether the title is italic
    lineHeight?: number; // Line height of the title in px
    underline?: boolean; // Whether the title is underlined
  }; // Title styling, applied if a title is displayed.
  tooltip?: {
    fontSize?: number; // Font size of the tooltip in px
    background?: string; // Background color of the tooltip
    lineHeight?: number; // Line height of the tooltip in px
    opacity?: number; // Opacity of the tooltip
  }; // Tooltip styling, applied if a tooltip is displayed (e.g. on hover over a bar in a bar chart).
}

import { ThemeConfig } from '@luzmo/dashboard-contents-types';

// In your chart.ts file
export function render({
  container,
  data = [],
  slots = [],
  slotConfigurations = [],
  options = {},
  language = 'en',
  dimensions: { width = 600, height = 400 } = {}
}: ChartParams): void {
  // Extract theme from options
  const theme: ThemeConfig = options.theme ?? {};

  // Clear container and set background
  container.innerHTML = '';
  container.style.backgroundColor = theme.itemsBackground;

  // Create main chart container with dynamic theme properties
  const chartContainer = document.createElement('div');
  chartContainer.className = 'chart-container';
  chartContainer.style.fontFamily = theme.font?.fontFamily || 'system-ui, sans-serif';
  chartContainer.style.fontSize = (theme.font?.fontSize || 13) + 'px';

  // Add a title that uses mainColor
  const titleElement = document.createElement('h2');
  titleElement.textContent = 'Chart Title';
  titleElement.style.color = theme.mainColor;

  chartContainer.appendChild(titleElement);
}

.bar-chart-container {
  width: 100%;
  height: 100%;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

.chart-title {
  font-size: 16px;
  font-weight: 600;
  text-align: center;
}

.axis path,
.axis line {
  stroke: #e0e0e0;
}

.axis text {
  font-size: 12px;
  fill: #666;
}

.bar {
  transition: opacity 0.2s;
}

.bar:hover {
  opacity: 0.8;
}

.legend-item {
  display: inline-flex;
  align-items: center;
  margin-right: 10px;
  font-size: 12px;
}

import type { ItemFilter } from '@luzmo/dashboard-contents-types';

// Example of sending a filter event
function sendFilterEvent(filters: ItemFilter[]): void {
  const eventData: { type: 'setFilter'; filters: ItemFilter[] } = {
    type: 'setFilter',  // Must always be 'setFilter'
    filters: filters
  };

  // Post message to parent window
  window.parent.postMessage(eventData, '*');
}

function clearFilterEvent(): void {
  sendFilterEvent([]);
}

// Example usage in a click handler
function onBarClick(category: string): void {
  const filters: ItemFilter[] = [
    {
      expression: '? = ?',  // Filter expression
      parameters: [
        {
          columnId: 'category-column-id',  // Column to filter on
          datasetId: 'dataset-id'          // Dataset containing the column
        },
        category  // Value to filter by
      ]
    }
  ];

  sendFilterEvent(filters);
}

interface ItemFilter {
  // Filter expression from a predefined list
  expression: '? = ?' | '? != ?' | '? in ?' | '? not in ?' | '? like ?' | '? not like ?' |
              '? starts with ?' | '? not starts with ?' | '? ends with ?' | '? not ends with ?' |
              '? < ?' | '? <= ?' | '? > ?' | '? >= ?' | '? between ?' | '? is null' | '? is not null';

  // Filter parameters
  parameters: [
    {
      columnId?: string;    // Column to filter on
      datasetId?: string;   // Dataset containing the column
      level?: number;       // Optional level for hierarchical or datetime data
    },
    number | string         // Value to filter by
  ];
}

const numericFilter: ItemFilter = {
  expression: '? >= ?',
  parameters: [
    {
      columnId: '<revenue column id>',
      datasetId: '<sales dataset id>'
    },
    100
  ]
};

const datetimeFilter: ItemFilter = {
  expression: '? >= ?',
  parameters: [
    {
      columnId: '<created_at column id>',
      datasetId: '<sales dataset id>'
    },
    '2025-01-01T00:00:00.000Z'
  ]
};

const hierarchyFilter: ItemFilter = {
  expression: '? = ?',
  parameters: [
    {
      columnId: '<region column id>',
      datasetId: '<sales dataset id>'
    },
    'North America'
  ]
};

type CustomChartEvent = {
  type: 'customEvent';
  data: Record<string, unknown>;
};

// Example of sending a custom event
function sendCustomEvent(eventType: string, data: Record<string, unknown>): void {
  const eventData: CustomChartEvent = {
    type: 'customEvent',  // Must always be 'customEvent'
    data: {
      eventType: eventType,  // Your custom event type
      ...data                // Any additional data you want to send
    }
  };

  // Post message to parent window
  window.parent.postMessage(eventData, '*');
}

// Example usage in a click handler
function onDataPointClick(category: string, value: number): void {
  sendCustomEvent('dataPointSelected', {
    category: category,
    value: value,
    timestamp: new Date().toISOString()
  });
}

window.parent.postMessage({ type: 'queryLoaded', query }, '*');

cd projects/custom-chart
npm install <package-name>

npm run build

npm run validate