Dashboard Builder

Build a utility module for creating and managing dashboard structures with tiles, tabs, layout positioning, and cross-tile filtering capabilities.

Requirements

Your module should provide functions for:

1. Dashboard Tile Creation

Create tiles with proper type, positioning, and properties. Support different tile types including chart tiles, markdown tiles, and SQL chart tiles. Each tile must have a unique UUID, grid position coordinates (x, y, width, height), and an optional tab UUID for tab organization.

2. Tab Validation

Validate that selected tab UUIDs actually exist within a dashboard's tiles. When tab UUIDs are provided for filtering, ensure at least one of them exists in the dashboard's tile collection. If no valid tabs are found, throw an appropriate error.

3. Tile Layout Positioning

Calculate appropriate positioning for tiles in a grid layout. Implement logic to determine x, y coordinates and dimensions (width and height) for new tiles, considering existing tile positions to avoid overlaps. Support different default sizes for different tile types.

4. Dashboard Filter Targeting

Apply dashboard-level filters to specific tiles using tile targeting configuration. Given a set of dashboard filters and a tile UUID, extract only the filters that should apply to that specific tile. Handle tile target overrides where filters can be customized or disabled on a per-tile basis.

Test Cases

• Creating a chart tile with grid position (x: 0, y: 0, w: 15, h: 9) and a tab UUID returns a tile with correct type and properties @test
• Creating a markdown tile with custom content and positioning (x: 15, y: 0, w: 10, h: 6) returns a markdown tile with the specified content @test
• Validating tabs when at least one selected tab UUID exists in dashboard tiles does not throw an error @test
• Validating tabs when no selected tab UUIDs exist in dashboard tiles throws a ParameterError @test
• Finding next available position for a new tile in a grid with existing tiles returns non-overlapping coordinates @test
• Filtering dashboard filters for a specific tile UUID returns only filters that target that tile @test
• Filtering dashboard filters respects tile target overrides where a filter is disabled (false) for specific tiles @test

Implementation

@generates

API

/**
 * Creates a dashboard chart tile with the specified configuration
 */
export function createChartTile(
    uuid: string,
    savedChartUuid: string,
    x: number,
    y: number,
    w: number,
    h: number,
    tabUuid?: string
): DashboardChartTile;

/**
 * Creates a dashboard markdown tile with the specified configuration
 */
export function createMarkdownTile(
    uuid: string,
    title: string,
    content: string,
    x: number,
    y: number,
    w: number,
    h: number,
    tabUuid?: string
): DashboardMarkdownTile;

/**
 * Validates that selected tab UUIDs exist in the dashboard tiles.
 * Throws ParameterError if none of the selected tabs exist.
 */
export function validateSelectedTabs(
    selectedTabs: string[] | null,
    dashboardTiles: DashboardTile[]
): void;

/**
 * Calculates the next available position for a new tile in the grid.
 * Returns an object with x, y coordinates for the new tile.
 */
export function getNextTilePosition(
    existingTiles: DashboardTile[],
    tileWidth: number,
    tileHeight: number,
    gridWidth?: number
): { x: number; y: number };

/**
 * Gets dashboard filters that apply to a specific tile.
 * Respects tile target overrides and filters out disabled filters.
 */
export function getDashboardFiltersForTile(
    tileUuid: string,
    dashboardFilters: DashboardFilters
): DashboardFilters;

Dependencies { .dependencies }

@lightdash/common { .dependency }

Provides dashboard types, tile types, filter types, and utilities for Lightdash BI platform.