TileLibraryModal Documentation

Purpose

The TileLibraryModal component serves as a user interface element within the Vantage analytics & data platform. It allows users to browse a library of predefined tiles that can be added to their dashboards, enhancing the flexibility and customization of their data visualization experience. Users can filter tiles by categories, search for specific tiles, and create custom tiles directly from this modal.

Functionality Overview

The modal integrates with the dashboard state management to fetch and display tile presets. It features a two-column layout with a sidebar for tile categories and a main content area for displaying tile options. Users can see available tiles, create custom tiles, and add tiles to their dashboard seamlessly.

Settings

1. isOpen

• Type: boolean
• Description: Determines whether the modal is visible or not. Setting this to true opens the modal, while false hides it.
• Default Value: false

2. onClose

• Type: function
• Description: A callback function that is invoked when the modal is closed. This typically updates the parent component's state to reflect the modal's closed state.
• Default Value: None (must be provided)

Internal State Variables (Managed by the Component)

3. presets

• Type: array
• Description: Holds the list of tile presets fetched from an API. This array will be used to render the available tiles in the modal.
• Default Value: [] (empty array)

4. categories

• Type: array
• Description: Stores the categories of tiles retrieved from the API. This is used for creating the sidebar tabs.
• Default Value: [] (empty array)

5. search

• Type: string
• Description: Represents the current search input by the user. This is used to filter the displayed tiles based on user input.
• Default Value: "" (empty string)

6. activeCategory

• Type: string
• Description: Indicates the currently active tile category. The value affects the displayed tile list based on the selected category.
• Default Value: "All"

How It Works

When the TileLibraryModal is opened (isOpen is true), it triggers an API call to fetch tile presets and categories. Selected categories can filter the displayed tiles, while the search input can further refine the displayed results. The user can add tiles to their dashboard by clicking on them or create new custom tiles, all while interacting with a clean and intuitive UI.

API Interaction

1. Fetching Tiles: The load function uses fetch to call /api/dashboard/load-tile-presets.
2. Data Handling: If the API call succeeds, it updates the presets and categories state. If it fails, it resets these to empty.

Expected Data

The TileLibraryModal component expects data in the following formats:

• Presets: Array of tile objects that should include at least fields like id, title, description, and category.
• Categories: Array of category objects, which should include id, category_name, and optionally icon and color for rendering in the sidebar.

Integrations

The component utilizes:

• Icons: From the lucide-react library to enhance UI by providing visual representation for categories and actions.
• Modal Provider: For handling modal presentation via the useModal hook to open the edit tile modal upon selection.
• Dashboard Store: Uses the useDashboardStore to add tiles.

Use Cases & Examples

Use Case 1: Dashboard Customization

A data analyst may want to customize their dashboard by adding specific visualizations that highlight key metrics. Using the TileLibraryModal, they can easily browse through available tiles, select the relevant ones, and add them directly to their existing layout.

Use Case 2: Tile Creation

A marketing manager wishes to create a custom tile that displays specific campaign performance metrics. They can navigate to the TileLibraryModal, create a new tile, and configure it in the subsequent edit modal.

Use Case 3: Spacer Inclusion

A designer wants to create intentional gaps between certain tiles for improved visual appeal. They can utilize the modal to add spacer tiles that enhance the overall layout.

Detailed Example Configuration

Use Case: Creating a Custom Tile for a Marketing Campaign.

Configuration Data:

{
    title: "New Custom Marketing Tile",
    subtitle: "Configure your campaign metrics",
    forceId: `node_${Date.now()}_${Math.floor(Math.random() * 1000)}`,
    config: {
        tile_type: 'stat',
        min_w: 2,
        min_h: 1,
        value: '50%',
        stats: [{ value: '50%', label: 'Conversion Rate' }],
        backgroundColor: '#ffcc00'
    },
    tile_presets: { tile_type: 'stat' }
}

In this example, the user selects the "Create Custom Tile" option from the TileLibraryModal, fills out the tile details, and then adds it to their dashboard, closing the modal afterward. This custom tile now showcases the marketing campaign's performance effectively.