> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebuly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Components

> Web components for rendering Nebuly charts

## Chart Components

The Nebuly chart component library provides a set of web components for rendering various types of charts using Chart.js. All components accept data as JSON strings and support customization through options.

### Common Properties

All chart components share these common properties:

<ParamField path="data" type="string" required>
  JSON string containing the chart data. Must conform to the `ChartData` type structure.
</ParamField>

<ParamField path="options" type="string">
  Optional JSON string containing chart customization options. Must conform to the `ChartCustomizationOptions` type structure.
</ParamField>

## 🧩 nebuly-metric-chart

Displays a single metric value with trend information and percentage change.

### Properties

<ParamField path="data" type="string" required>
  JSON string containing metric data with current and previous values for trend calculation.
</ParamField>

<ParamField path="options" type="string">
  Optional customization options for colors and display settings.
</ParamField>

### Example

```html theme={null}
<nebuly-metric-chart 
  data='{"id":"metric-1","name":"Total Users","variables":["users"],"visualizationType":"formula","data":[{"label":"current","data":[{"x":0,"y":1250}]},{"label":"previous","data":[{"x":0,"y":1000}]}]}'
  options='{"colors":["#0072f5","#ff6b6b"]}'>
</nebuly-metric-chart>
```

## 🧩 nebuly-horizontal-bar-chart

Renders a horizontal bar chart with resizable legend and chart areas.

### Properties

<ParamField path="data" type="string" required>
  JSON string containing bar chart data with labels and values.
</ParamField>

<ParamField path="options" type="string">
  Optional customization options for colors and display settings.
</ParamField>

### Features

* **Resizable Layout**: Users can drag the resize slider to adjust the legend and chart area proportions
* **Sentiment Support**: Special handling for sentiment-based breakdowns with appropriate colors
* **Percentage Display**: Automatic percentage formatting when `displayType` is "percentage"
* **Interactive Tooltips**: Hover tooltips with detailed information

### Example

```html theme={null}
<nebuly-horizontal-bar-chart 
  data='{"id":"bar-1","name":"User Sentiment","type":"bar","variables":["sentiment"],"breakdown":"sentiment","xLabelValues":["positive","negative","neutral"],"data":[{"label":"positive","data":[{"x":0,"y":45}]},{"label":"negative","data":[{"x":1,"y":20}]},{"label":"neutral","data":[{"x":2,"y":35}]}]}'
  options='{"colors":["#10b981","#ef4444","#6b7280"]}'>
</nebuly-horizontal-bar-chart>
```

## 🧩 nebuly-stacked-bar-chart

Renders a vertical stacked bar chart for comparing multiple data series.

### Properties

<ParamField path="data" type="string" required>
  JSON string containing stacked bar chart data with multiple datasets.
</ParamField>

<ParamField path="options" type="string">
  Optional customization options for colors and display settings.
</ParamField>

### Features

* **Stacked Display**: Multiple data series are stacked vertically
* **Time Series Support**: Automatic time-based formatting for temporal data
* **Legend Integration**: Built-in legend with color-coded labels
* **Percentage Labels**: Optional data labels showing percentage values

### Example

```html theme={null}
<nebuly-stacked-bar-chart 
  data='{"id":"stacked-1","name":"Monthly Breakdown","type":"bar","variables":["interactions"],"breakdown":"category","granularity":"month","xLabelValues":["2024-01","2024-02","2024-03"],"data":[{"label":"support","data":[{"x":0,"y":100},{"x":1,"y":120},{"x":2,"y":90}]},{"label":"sales","data":[{"x":0,"y":80},{"x":1,"y":95},{"x":2,"y":110}]}]}'
  options='{"colors":["#3b82f6","#10b981","#f59e0b"]}'>
</nebuly-stacked-bar-chart>
```

## 🧩 nebuly-line-chart

Renders a line chart for time series data with support for forecasts and multiple data series.

### Properties

<ParamField path="data" type="string" required>
  JSON string containing line chart data with time series information.
</ParamField>

<ParamField path="options" type="string">
  Optional customization options for colors and display settings.
</ParamField>

### Features

* **Time Series**: Full support for time-based data with automatic axis formatting
* **Forecast Support**: Special handling for forecast data with different styling
* **Interactive Zoom/Pan**: Built-in zoom and pan functionality
* **Multiple Series**: Support for multiple data lines with different colors
* **Dashed Lines**: Automatic dashed styling for average, forecast, and previous data
* **Hover Effects**: Interactive highlighting on hover

### Example

```html theme={null}
<nebuly-line-chart 
  data='{"id":"line-1","name":"User Growth","type":"line","variables":["users"],"granularity":"day","xLabelValues":["2024-01-01","2024-01-02","2024-01-03"],"data":[{"label":"current","data":[{"x":0,"y":100},{"x":1,"y":120},{"x":2,"y":135}]},{"label":"forecast","data":[{"x":2,"y":135},{"x":3,"y":150},{"x":4,"y":165}]}]}'
  options='{"colors":["#3b82f6","#10b981"]}'>
</nebuly-line-chart>
```

## 🧩 nebuly-distributed-line-chart

A specialized line chart component for distributed data visualization.

### Properties

<ParamField path="data" type="string" required>
  JSON string containing distributed line chart data.
</ParamField>

<ParamField path="options" type="string">
  Optional customization options for colors and display settings.
</ParamField>

### Features

* **Distributed Data**: Optimized for non-temporal distributed data
* **Category Axis**: Uses category-based x-axis instead of time series
* **Simplified Rendering**: Wrapper around `nebuly-line-chart` with distributed-specific settings

### Example

```html theme={null}
<nebuly-distributed-line-chart 
  data='{"id":"distributed-1","name":"Category Distribution","type":"distributed","variables":["count"],"xLabelValues":["Category A","Category B","Category C"],"data":[{"label":"values","data":[{"x":0,"y":25},{"x":1,"y":40},{"x":2,"y":35}]}]}'
  options='{"colors":["#8b5cf6"]}'>
</nebuly-distributed-line-chart>
```

## Data Structure

All components expect data in the following `ChartData` format:

```typescript theme={null}
type ChartData = {
  id: string;                    // Unique chart identifier
  name: string;                  // Chart display name
  type: string;                  // Chart type ("line", "bar", etc.)
  variables: string[];           // Data variables
  visualizationType?: string;    // Visualization type
  displayType?: string;          // Display type ("percentage", etc.)
  breakdown?: string;            // Breakdown dimension
  timeRange?: TimeRange;         // Time range for the data
  granularity?: string;          // Time granularity
  xLabelValues: string[];        // X-axis labels
  data: DatasetDatapoint[];      // Chart data points
};

type DatasetDatapoint = {
  label: string;                 // Dataset label
  data: Array<{                  // Data points
    x: number;                   // X coordinate
    y: number;                   // Y coordinate
    user?: string;               // Optional user identifier
  }>;
};
```

## Customization Options

Components support customization through the `ChartCustomizationOptions` type:

```typescript theme={null}
type ChartCustomizationOptions = {
  colors?: string[];             // Custom color palette
  // Additional options will be added in the future
};
```

## Styling

All components are self-contained and include their own CSS. They use the Inter font family and follow a consistent design system. Components automatically load required fonts and handle responsive sizing.

## Browser Support

These web components are built with Lit and support all modern browsers that support:

* Custom Elements v1
* Shadow DOM v1
* ES2015+ features