# Luzmo Flex SDK Documentation

> Complete reference for Luzmo Flex SDK. Create code-first data visualizations embedded in web applications using React, Angular, Vue, or vanilla JavaScript.

**Current Schema Version: v0.1.97**

> **Version Note**: This documentation describes chart configuration for schema version **0.1.97**. Chart slots, options, and structure are versioned and may differ between versions. When creating charts programmatically, ensure you use the schema structure that corresponds to your target version. Luzmo automatically upgrades existing dashboards to newer schema versions, but the JSON structure for slots and options must match the version you're targeting.

## Overview

Luzmo Flex enables developers to create customizable visualizations entirely from code, allowing hyper-personalized data analytics products without using the Luzmo dashboard builder.

> **Important: Chart Sizing** - Charts require explicit dimensions to render. Either:
> 1. Place the chart in a container element with defined `height` and `width` (CSS or inline styles), or
> 2. Set `height` and `width` directly on the chart component itself
>
> Without defined dimensions, the chart will have 0 height and will not be visible.

## Installation

### Web Components (Vanilla JS)

```bash
npm install @luzmo/embed
```

```javascript
import '@luzmo/embed';
```

```html
<luzmo-embed-viz-item
  type="bar-chart"
  authKey="<embed-key>"
  authToken="<embed-token>"
  slots='[...]'
  options='{...}'
></luzmo-embed-viz-item>
```

### React

```bash
npm install @luzmo/react-embed
```

```jsx
import { LuzmoVizItemComponent } from '@luzmo/react-embed';

function Chart() {
  return (
    // Container with defined dimensions (or set width/height on the component)
    <div style={{ width: '100%', height: '400px' }}>
      <LuzmoVizItemComponent
        type="bar-chart"
        authKey="<embed-key>"
        authToken="<embed-token>"
        slots={[...]}
        options={{...}}
      />
    </div>
  );
}
```

### Angular

```bash
npm install @luzmo/ngx-embed
```

```typescript
import { NgxLuzmoVizItemComponent } from '@luzmo/ngx-embed';

@Component({
  imports: [NgxLuzmoVizItemComponent]
})
```

```html
<luzmo-viz-item
  type="bar-chart"
  [authKey]="authKey"
  [authToken]="authToken"
  [slots]="slots"
  [options]="options"
></luzmo-viz-item>
```

### Vue

```bash
npm install @luzmo/vue-embed
```

```javascript
import VueLuzmo from '@luzmo/vue-embed';
app.use(VueLuzmo);
```

```vue
<template>
  <luzmo-viz-item
    type="bar-chart"
    :authKey="authKey"
    :authToken="authToken"
    :slots="slots"
    :options="options"
  />
</template>
```

### React Native

```bash
npm install @luzmo/react-native-embed
```

```jsx
import { LuzmoVizItemComponent } from '@luzmo/react-native-embed';
```

## Server Configuration

Set server endpoints based on your Luzmo region:

| Region | appServer | apiHost |
|--------|-----------|---------|
| EU (Default) | `https://app.luzmo.com` | `https://api.luzmo.com` |
| US | `https://app.us.luzmo.com` | `https://api.us.luzmo.com` |
| VPC | `https://app.{vpc}.luzmo.com` | `https://api.{vpc}.luzmo.com` |

## Component Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes* | Chart type identifier |
| `slots` | array | Yes* | Data slot configuration |
| `options` | object | No | Visual customization |
| `authKey` | string | Yes | Embed authorization key |
| `authToken` | string | Yes | Embed authorization token |
| `appServer` | string | No | Luzmo app server URL |
| `apiHost` | string | No | Luzmo API server URL |
| `filters` | array | No | Runtime filters |
| `contextId` | string | No | Cross-filtering context |
| `canFilter` | string/array | No | Cross-filtering targets |
| `dashboardId` | string | Yes** | Dashboard ID (when embedding existing) |
| `itemId` | string | Yes** | Item ID (when embedding existing) |
| `language` | string | No*** | Locale code (e.g., 'en', 'fr') |
| `timezone` | string | No | IANA timezone ID |
| `theme` | string | No | Theme ID |

*Required for code-first charts
**Required for embedding existing dashboard items
***Recommended: Always provide `language` to ensure localized fields (like `title`, `label`) are resolved correctly

## Chart Types

**Schema Version: v0.1.97** (Latest)

**JSON Schema Base URL**: `https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/`

Each chart type has a dereferenced JSON schema that defines **all available slots and options** for that specific chart. These schemas are the authoritative source for discovering configurable properties—always consult the relevant schema to know exactly which slots, options, and values are valid for a given chart type.

> **Important**: The schemas below are specific to version **0.1.97**. Structure changes occur between versions. When programmatically creating or modifying charts, always reference the schema for your target version.

### Standard Charts

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `area-chart` | Stacked or layered area chart | x-axis, measure, legend | [area-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/area-chart.schema.json) |
| `bar-chart` | Horizontal bar chart | y-axis, measure, legend | [bar-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bar-chart.schema.json) |
| `column-chart` | Vertical bar/column chart | x-axis, measure, legend | [column-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/column-chart.schema.json) |
| `line-chart` | Line chart with optional markers | x-axis, measure, legend | [line-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/line-chart.schema.json) |
| `combination-chart` | Mixed chart types (line + column) | x-axis, measure, legend | [combination-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/combination-chart.schema.json) |
| `scatter-plot` | X-Y scatter plot | x-axis, y-axis, size, legend | [scatter-plot.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/scatter-plot.schema.json) |
| `bubble-chart` | Bubble chart with sizing | x-axis, y-axis, size, legend | [bubble-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bubble-chart.schema.json) |
| `donut-chart` | Donut/pie chart | category, measure | [donut-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/donut-chart.schema.json) |
| `funnel-chart` | Funnel visualization | category, measure | [funnel-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/funnel-chart.schema.json) |
| `radar-chart` | Spider/radar chart | category, measure, legend | [radar-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/radar-chart.schema.json) |
| `pyramid-chart` | Pyramid chart | category, measure | [pyramid-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/pyramid-chart.schema.json) |

### Maps

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `choropleth-map` | Filled region map | location, measure | [choropleth-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/choropleth-map.schema.json) |
| `marker-map` | Point markers on map | latitude, longitude, measure | [marker-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/marker-map.schema.json) |
| `hexbin-map` | Hexagonal binning map | latitude, longitude, measure | [hexbin-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/hexbin-map.schema.json) |
| `symbol-map` | Proportional symbol map | latitude, longitude, size | [symbol-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/symbol-map.schema.json) |
| `route-map` | Connected route lines | latitude, longitude, order | [route-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/route-map.schema.json) |
| `spike-map` | 3D spike visualization | latitude, longitude, measure | [spike-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/spike-map.schema.json) |

### Tables

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `regular-table` | Standard data table | columns (multiple) | [regular-table.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/regular-table.schema.json) |
| `pivot-table` | Cross-tabulation table | rows, columns, measure | [pivot-table.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/pivot-table.schema.json) |
| `heat-table` | Table with color gradient | rows, columns, measure | [heat-table.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/heat-table.schema.json) |

### Gauges & Numbers

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `circular-gauge` | Circular progress gauge | measure, target | [circular-gauge.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/circular-gauge.schema.json) |
| `speedometer-chart` | Speedometer-style gauge | measure | [speedometer-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/speedometer-chart.schema.json) |
| `bullet-chart` | Bullet comparison chart | measure, target | [bullet-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/bullet-chart.schema.json) |
| `evolution-number` | Number with change indicator | measure | [evolution-number.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/evolution-number.schema.json) |
| `conditional-number` | Number with conditional formatting | measure | [conditional-number.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/conditional-number.schema.json) |

### Filters

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `date-filter` | Date/datetime picker | datetime | [date-filter.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/date-filter.schema.json) |
| `dropdown-filter` | Dropdown selection | category | [dropdown-filter.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/dropdown-filter.schema.json) |
| `slicer-filter` | Button/chip selection | category | [slicer-filter.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slicer-filter.schema.json) |
| `slider-filter` | Numeric range slider | numeric | [slider-filter.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slider-filter.schema.json) |
| `search-filter` | Text search filter | category | [search-filter.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/search-filter.schema.json) |

### Hierarchical

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `treemap-chart` | Nested rectangles | hierarchy, measure | [treemap-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/treemap-chart.schema.json) |
| `sunburst-chart` | Radial hierarchy | hierarchy, measure | [sunburst-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/sunburst-chart.schema.json) |
| `sankey-diagram` | Flow diagram | source, target, measure | [sankey-diagram.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/sankey-diagram.schema.json) |
| `circle-pack-chart` | Packed circles | hierarchy, measure | [circle-pack-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/circle-pack-chart.schema.json) |

### Statistical

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `box-plot` | Box and whisker plot | category, measure | [box-plot.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/box-plot.schema.json) |
| `strip-plot` | Strip/dot plot | category, measure | [strip-plot.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/strip-plot.schema.json) |
| `parallel-coordinates-plot` | Multi-axis comparison | dimensions (multiple) | [parallel-coordinates-plot.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/parallel-coordinates-plot.schema.json) |
| `heat-map` | 2D density heatmap | x-axis, y-axis, measure | [heat-map.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/heat-map.schema.json) |

### Other

| Type | Description | Key Slots | Schema |
|------|-------------|-----------|--------|
| `wordcloud-chart` | Word cloud | category, measure | [wordcloud-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/wordcloud-chart.schema.json) |
| `ohlc-chart` | Open-high-low-close (financial) | datetime, open, high, low, close | [ohlc-chart.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/ohlc-chart.schema.json) |
| `image` | Image display | - | [image.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/image.schema.json) |
| `video` | Video embed | - | [video.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/video.schema.json) |
| `text` | Rich text | - | [text.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/text.schema.json) |

### Additional Schemas

| Schema | Description |
|--------|-------------|
| [slots.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slots.schema.json) | Complete slot definitions for all chart types |
| [options.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/options.schema.json) | Common options schema |
| [viz-item-type.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/viz-item-type.schema.json) | All visualization type identifiers |

## Slots Configuration

Slots define what data appears in the chart. Each slot contains an array of column configurations.

> **Discovering Available Slots**: Each chart type supports different slots (e.g., `x-axis`, `measure`, `legend`). Consult the chart-specific JSON schema (linked in the [Chart Types](#chart-types) table) to see which slots are available for that chart type and their configuration options.

**Full slots schema**: [slots.schema.json](https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/slots.schema.json)

### Basic Slot Structure

```javascript
slots: [
  {
    name: 'x-axis',  // Slot name varies by chart type
    content: [
      {
        type: 'hierarchy',  // Column type: hierarchy, numeric, datetime
        columnId: '<column-uuid>',  // or 'column' for legacy
        datasetId: '<dataset-uuid>', // or 'set' for legacy
        label: { en: 'Category' }
      }
    ]
  },
  {
    name: 'measure',
    content: [
      {
        type: 'numeric',
        columnId: '<column-uuid>',
        datasetId: '<dataset-uuid>',
        aggregationFunc: 'sum',  // sum, count, avg, min, max, distinctcount
        format: '$,.2f',  // D3 format string
        label: { en: 'Revenue' }
      }
    ]
  }
]
```

## Filling Slots by Data Type

The `type` property in slot content determines how to configure the column. Choose based on your source column's data type.

### 1. Numeric Data (type: "numeric")

Use for **measure slots** (values to aggregate) or when numeric data should be treated as a category.

**As a Measure (most common):**
```javascript
{
  type: 'numeric',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  aggregationFunc: 'sum',     // REQUIRED for measures
  format: '$,.2f',            // D3 number format (optional)
  label: { en: 'Revenue' },
  color: '#1a73e8'            // Series color when multiple measures
}
```

**Aggregation functions**: `sum`, `average`, `count`, `distinctcount`, `min`, `max`, `median`, `stddev`, `rate`, `cumulativesum`, `weightedaverage`, `histogram`

**D3 Format Examples**:
- `$,.2f` → $1,234.56 (currency with 2 decimals)
- `,.0f` → 1,235 (integer with thousands separator)
- `.2%` → 12.35% (percentage)
- `.3s` → 1.23k (SI prefix)

**As a Category (binned numeric ranges):**
```javascript
{
  type: 'numeric',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  bins: {
    enabled: true,
    number: 10              // Number of bins/ranges
  }
}
```

### 2. Categorical Data (type: "hierarchy")

Use for **dimension slots** (x-axis, y-axis, legend, category) to group data.

**Standard Category:**
```javascript
{
  type: 'hierarchy',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  level: 1,                   // Hierarchy level (1 = top)
  label: { en: 'Product Category' }
}
```

**Multi-level Hierarchy** (for drilldown):
```javascript
// Level 1 - Top level (e.g., Country)
{ type: 'hierarchy', columnId: '<country-uuid>', datasetId: '<uuid>', level: 1 }
// Level 2 - Second level (e.g., City)
{ type: 'hierarchy', columnId: '<city-uuid>', datasetId: '<uuid>', level: 2, lowestLevel: 2 }
```

**Hierarchy as Measure** (counting occurrences):
```javascript
{
  type: 'hierarchy',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  aggregationFunc: 'count',        // or 'distinctcount'
  label: { en: 'Number of Categories' }
}
```

### 3. Datetime Data (type: "datetime")

Use for **time-based dimension slots** to show trends over time.

**Standard Time Dimension:**
```javascript
{
  type: 'datetime',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  level: 3,                   // Time granularity (see levels below)
  label: { en: 'Month' }
}
```

**Datetime Levels:**
| Level | Granularity | Example Output |
|-------|-------------|----------------|
| 1 | Year | 2024 |
| 2 | Quarter | Q1 2024 |
| 3 | Month | Jan 2024 |
| 4 | Week | Week 1 |
| 5 | Day | Jan 15, 2024 |
| 6 | Hour | 14:00 |
| 7 | Minute | 14:30 |
| 8 | Second | 14:30:45 |
| 9 | Millisecond | 14:30:45.123 |

**Display Modes** (alternative formatting):
```javascript
{
  type: 'datetime',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  level: 5,
  datetimeDisplayMode: 'weekday_name',  // Show "Monday", "Tuesday", etc.
  weekDayNameFormat: 'short'            // "Mon", "Tue" (or 'long', 'letter')
}
```

Display modes: `default`, `month_name`, `weekday_name`, `day_in_month`, `day_in_year`, `week_number`, `month_number`, `quarter_number`, `hour_in_day`, `minute_in_hour`, `second_in_minute`

**Datetime as Measure:**
```javascript
{
  type: 'datetime',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  aggregationFunc: 'count',    // or 'distinctcount'
  label: { en: 'Number of Dates' }
}
```

**Period Over Period Comparison:**
```javascript
{
  type: 'numeric',
  columnId: '<uuid>',
  datasetId: '<uuid>',
  aggregationFunc: 'sum',
  periodOverPeriod: {
    type: 'percentageChange',  // 'none', 'past', 'absoluteChange', 'percentageChange'
    level: 3,                  // Compare by month
    quantity: 1                // Compare to 1 period ago
  }
}
```

### 4. Mixed Data Scenarios

**Scenario A: Show revenue by price range** (numeric as category)
```javascript
slots: [
  {
    name: 'x-axis',
    content: [{
      type: 'numeric',
      columnId: '<price-uuid>',
      datasetId: '<uuid>',
      bins: { enabled: true, number: 5 }  // Creates 5 price ranges
    }]
  },
  {
    name: 'measure',
    content: [{
      type: 'numeric',
      columnId: '<revenue-uuid>',
      datasetId: '<uuid>',
      aggregationFunc: 'sum'
    }]
  }
]
```

**Scenario B: Count unique customers over time** (hierarchy in measure)
```javascript
slots: [
  {
    name: 'x-axis',
    content: [{
      type: 'datetime',
      columnId: '<date-uuid>',
      datasetId: '<uuid>',
      level: 3
    }]
  },
  {
    name: 'measure',
    content: [{
      type: 'hierarchy',
      columnId: '<customer-uuid>',
      datasetId: '<uuid>',
      aggregationFunc: 'distinctcount',
      label: { en: 'Unique Customers' }
    }]
  }
]
```

**Scenario C: Multiple measures with different types**
```javascript
slots: [
  {
    name: 'x-axis',
    content: [{
      type: 'datetime',
      columnId: '<date-uuid>',
      datasetId: '<uuid>',
      level: 3
    }]
  },
  {
    name: 'measure',
    content: [
      {
        type: 'numeric',
        columnId: '<revenue-uuid>',
        datasetId: '<uuid>',
        aggregationFunc: 'sum',
        color: '#1a73e8',
        label: { en: 'Revenue' }
      },
      {
        type: 'hierarchy',
        columnId: '<order-uuid>',
        datasetId: '<uuid>',
        aggregationFunc: 'distinctcount',
        color: '#34a853',
        label: { en: 'Order Count' }
      }
    ]
  }
]
```

### Slot Content Properties Reference

```javascript
{
  // Required
  type: 'numeric',           // Column type
  columnId: '<uuid>',        // Column identifier (or 'column')
  datasetId: '<uuid>',       // Dataset identifier (or 'set')
  
  // Optional
  label: { en: 'Label' },    // Display label (localized)
  format: '$,.2f',           // D3 format for numbers/dates
  color: '#FF5733',          // Series color
  aggregationFunc: 'sum',    // Aggregation for measures
  level: 1,                  // Hierarchy/datetime level
  
  // Datetime specific
  datetimeDisplayMode: 'default',  // default, month_name, weekday_name, etc.
  weekStart: 'monday',       // monday or sunday
  weekDayNameFormat: 'short', // short, long, letter
  monthNameFormat: 'short',   // short, long, letter
  
  // Numeric specific
  bins: { enabled: true, number: 10 },  // Bin numeric values
  currency: '€',             // Currency symbol (when subtype is 'currency')
  
  // Formula (instead of column)
  formula: 'SUM(dataset:column) / 100',  // Ad-hoc formula
  formulaId: '<formula-uuid>'             // Reference to saved formula
}
```

### Common Slot Names by Chart Type

**Column/Bar/Line/Area Charts:**
- `x-axis`: Category dimension
- `y-axis`: Category dimension (bar chart)
- `measure`: Numeric values
- `legend`: Grouping dimension

**Scatter/Bubble:**
- `x-axis`: Numeric X values
- `y-axis`: Numeric Y values
- `size`: Bubble size
- `legend`: Grouping

**Donut/Funnel:**
- `category`: Category dimension
- `measure`: Numeric values

**Maps:**
- `location`: Geographic column (choropleth)
- `latitude` / `longitude`: Coordinates
- `measure`: Value for coloring/sizing

**Tables:**
- First slot: Row dimensions
- Additional slots: Measure columns

## Options Configuration

Options control the visual appearance of charts.

> **Discovering Available Options**: Each chart type has different available options. Consult the chart-specific JSON schema (linked in the [Chart Types](#chart-types) table) to see all valid options for that chart type. The schema defines which properties are available and their expected types/values.

> **Avoid Duplicate Titles**: Do NOT add a chart `title` in options if the page already has an external title (e.g., an `<h1>` or heading above the chart). Set `display.title: false` in this case. Only use the chart's built-in title when embedding a standalone chart without surrounding context.

### Common Options

```javascript
options: {
  // Title - ONLY use if no external title exists on the page
  // If you have an <h1> or header above the chart, omit this and set display.title: false
  // MUST be an object with language keys directly, not a string!
  title: { en: 'Chart Title' }
  
  // Display
  display: {
    title: false,  // Set to false if using an external title
    legend: true,
    modeOption: false
  },
  
  // Legend
  legend: {
    position: 'right'  // top, right, bottom, left
  },
  
  // Color
  color: '#1a73e8',    // Primary color
  colorPalette: ['#1a73e8', '#34a853', '#fbbc04'],
  
  // Axes (for axis-based charts)
  axis: {
    x: {
      ticksMode: 'ticks',  // ticks, gridlines, hide
      color: '#666666'
    },
    y: {
      ticksMode: 'ticks',
      scale: 'linear',     // linear, logarithmic
      color: '#666666'
    }
  },
  
  // Grid
  grid: {
    x: { enabled: false, style: 'solid', opacity: 0.5 },
    y: { enabled: true, style: 'dashed', opacity: 0.3 }
  },
  
  // Tooltip
  tooltip: {
    enabled: true
  },
  
  // Interactivity
  interactivity: {
    exportAllowed: true,
    drilldownEnabled: false
  }
}
```

### Chart-Specific Options

**Column/Bar Charts:**
```javascript
{
  bars: {
    roundedCorners: 5,
    label: 'none'  // none, percentage, percentageCategory
  },
  mode: {
    type: 'grouped'  // grouped, stacked, stacked100
  }
}
```

**Line/Area Charts:**
```javascript
{
  lines: {
    smooth: false,
    showMarkers: true,
    markerShape: 'circle'  // circle, square, diamond
  },
  mode: {
    type: 'default'  // default, stacked, stacked100
  }
}
```

**Donut Chart:**
```javascript
{
  donut: {
    innerRadius: 50,    // 0-100 (0 = pie chart)
    startAngle: 0
  }
}
```

**Maps:**
```javascript
{
  map: {
    type: 'world',      // world, or specific region
    projection: 'mercator'
  }
}
```

**Tables:**
```javascript
{
  table: {
    columnWidths: 'auto',
    pagination: { enabled: true, pageSize: 25 },
    sorting: { enabled: true }
  }
}
```

## Filters

Apply filters to limit displayed data.

### Filter Structure

```javascript
filters: [
  {
    condition: 'and',  // or 'or' for OR grouping
    filters: [
      {
        expression: '? in ?',
        parameters: [
          {
            columnId: '<column-uuid>',
            datasetId: '<dataset-uuid>',
            level: 1  // For hierarchy/datetime
          },
          ['Value1', 'Value2']  // Filter values
        ]
      }
    ]
  }
]
```

### Filter Expressions

| Expression | Description | Value Type |
|------------|-------------|------------|
| `? = ?` | Equals | Single value |
| `? != ?` | Not equals | Single value |
| `? in ?` | In array | Array |
| `? not in ?` | Not in array | Array |
| `? > ?` | Greater than | Number/Date |
| `? >= ?` | Greater or equal | Number/Date |
| `? < ?` | Less than | Number/Date |
| `? <= ?` | Less or equal | Number/Date |
| `? like ?` | Contains | String |
| `? is null` | Is null | None |
| `? is not null` | Is not null | None |
| `? between ?` | Between | [min, max] |

### Date Filters

```javascript
{
  expression: '? >= ?',
  parameters: [
    { columnId: '<date-column>', datasetId: '<dataset>', level: 5 },
    '2024-01-01T00:00:00.000Z'  // ISO 8601 format
  ]
}
```

### Relative Date Filters

```javascript
// Last 30 days
{
  expression: 'last_now',
  parameters: [
    { columnId: '<date-column>', datasetId: '<dataset>' },
    { unit: 5, quantity: 29 }  // unit: 5=days, quantity: 29 (30-1)
  ]
}
```

## Component Methods

Access via ref:

```javascript
// React
const chartRef = useRef();
chartRef.current.getData();

// Angular
@ViewChild('chart') chartRef: NgxLuzmoVizItemComponent;
this.chartRef.getData();

// Vue
this.$refs.chart.getData();
```

### Available Methods

| Method | Description | Returns |
|--------|-------------|---------|
| `getData()` | Get current chart data | Promise<data[]> |
| `getFilters()` | Get applied filters | Promise<filters[]> |
| `refreshData()` | Refresh data from server | void |
| `exportData(format)` | Export chart | Promise (format: 'csv', 'xlsx', 'png') |
| `setFilters(filters)` | Apply filters programmatically | void |

## Component Events

| Event | Description | Payload |
|-------|-------------|---------|
| `load` | Chart code loaded | - |
| `rendered` | Chart fully rendered | - |
| `changedFilters` | Filters changed (user interaction) | { filters } |
| `exported` | Export completed | { format, data } |
| `customEvent` | Custom event from chart | { name, data } |

### Event Handling

```jsx
// React
<LuzmoVizItemComponent
  onRendered={() => console.log('Rendered')}
  onChangedFilters={(e) => console.log('Filters:', e.detail)}
/>
```

```html
<!-- Angular -->
<luzmo-viz-item
  (rendered)="onRendered()"
  (changedFilters)="onFiltersChange($event)"
></luzmo-viz-item>
```

> **Important**: These events are JavaScript events, not HTML attributes. The component does **not** add attributes like `rendered` to the DOM element. Do not use CSS selectors like `:not([rendered])` or `[rendered]` for loading states—they will not work. Instead, use JavaScript event listeners to track component state and update CSS classes manually if needed.

## Cross-Chart Filtering

Enable charts to filter each other.

```jsx
// Chart 1 - Filter source
<LuzmoVizItemComponent
  contextId="my-context"
  canFilter="all"  // or ['context-2', 'context-3']
  type="slicer-filter"
  slots={[...]}
/>

// Chart 2 - Filter target
<LuzmoVizItemComponent
  contextId="my-context"
  type="bar-chart"
  slots={[...]}
/>
```

## Embedding Existing Dashboard Items

Instead of creating charts from code, embed existing items:

```jsx
<LuzmoVizItemComponent
  dashboardId="<dashboard-uuid>"
  itemId="<item-uuid>"
  authKey="<embed-key>"
  authToken="<embed-token>"
/>
```

## Theming

Apply themes using a theme ID or inline custom theme configuration. Theme options control colors, fonts, backgrounds, and styling across the entire chart.

> **Discovering Theme Options**: Each chart type's JSON schema (linked in the [Chart Types](#chart-types) table) defines the full `theme` object structure under `options.theme`. Consult the schema for all available theme properties for your specific chart type.

### Theme by ID

Reference a pre-built or custom theme by its ID:

```jsx
<LuzmoVizItemComponent 
  options={{
    theme: {
      id: 'default'  // Built-in theme ID (see list below) or a saved theme UUID
    }
  }}
  ...
/>
```

**Built-in Theme IDs:**
| ID | Description |
|----|-------------|
| `default` | Light theme (default) |
| `default_dark` | Dark theme |
| `vivid` | Vivid theme |
| `seasonal` | Seasonal theme |
| `orion` | Orion theme |
| `royale` | Royale theme |
| `urban` | Urban theme |
| `pinky` | Pinky theme |
| `bliss` | Bliss theme |
| `radiant` | Radiant theme |
| `classic` | Classic theme |
| `classic_dark` | Classic dark theme |

### Inline Custom Theme

Define theme properties directly for full control over chart appearance:

```jsx
<LuzmoVizItemComponent
  options={{
    color: '#1a73e8',  // Main/primary color for the chart
    theme: {
      type: 'custom',  // Required when specifying custom theme options
      
      // Background
      itemsBackground: 'rgb(30, 30, 30)',  // Chart background color
      
      // Color palette for data series (bars, lines, slices, etc.)
      colors: [
        '#FFB74D',
        '#FFEB3B', 
        '#FF4081',
        '#40C4FF',
        '#66BB6A',
        '#BA68C8',
        '#FF5252',
        '#4DD0E1'
      ],
      
      // Typography
      font: {
        fontFamily: 'Roboto',  // Base font family
        fontSize: 14           // Base font size in px
      },
      
      // Title styling (when display.title is true)
      title: {
        fontSize: 18,
        bold: true,
        align: 'left'  // 'left', 'center', 'right'
      },
      
      // Axis styling
      axis: {
        fontSize: 12
      },
      
      // Legend styling (when display.legend is true)
      legend: {
        fontSize: 12,
        type: 'circle'  // 'normal', 'circle', 'line'
      },
      
      // Tooltip styling
      tooltip: {
        background: 'rgb(50, 50, 50)',
        fontSize: 12,
        opacity: 0.95
      },
      
      // Borders
      borders: {
        'border-style': 'solid',
        'border-color': 'rgb(60, 60, 60)',
        'border-radius': '8px',
        'border-top-width': '1px',
        'border-right-width': '1px',
        'border-bottom-width': '1px',
        'border-left-width': '1px'
      },
      
      // Shadow
      boxShadow: {
        size: 'M',  // 'none', 'S', 'M', 'L'
        color: 'rgb(0, 0, 0)'
      }
    }
  }}
  ...
/>
```

### Theme Properties Reference

| Property | Type | Description |
|----------|------|-------------|
| `type` | string | Set to `'custom'` when using custom theme options |
| `id` | string | Theme ID: `'seasonal'`, `'urban'`, or custom UUID |
| `itemsBackground` | string | Chart background color (rgb, hex, or color name) |
| `colors` | string[] | Array of colors for data series |
| `font.fontFamily` | string | Base font family for all text |
| `font.fontSize` | number | Base font size in px |
| `title.fontSize` | number | Title font size in px |
| `title.bold` | boolean | Bold title text |
| `title.align` | string | Title alignment: `'left'`, `'center'`, `'right'` |
| `axis.fontSize` | number | Axis labels font size in px |
| `legend.fontSize` | number | Legend font size in px |
| `legend.type` | string | Legend marker: `'normal'`, `'circle'`, `'line'` |
| `tooltip.background` | string | Tooltip background color |
| `tooltip.fontSize` | number | Tooltip font size in px |
| `tooltip.opacity` | number | Tooltip opacity (0-1) |
| `borders.*` | string | Border styling properties |
| `boxShadow.size` | string | Shadow size: `'none'`, `'S'`, `'M'`, `'L'` |
| `boxShadow.color` | string | Shadow color |

## Localization

The `language` attribute determines which translation is displayed for all localized text fields in the chart (such as `title`, `label`, etc.).

```jsx
<LuzmoVizItemComponent
  language="en"  // Locale code - determines which translation to display
  ...
/>
```

**Important**: All localized text fields (like `title` and `label`) must be objects with language codes as keys—not strings or nested structures. The component's `language` attribute selects which key to display:

```javascript
// If language="en", displays "Monthly Revenue"
// If language="nl", displays "Maandelijkse Omzet"
options: {
  title: { 
    en: 'Monthly Revenue',
    nl: 'Maandelijkse Omzet',
    fr: 'Revenus Mensuels'
  }
}

// Same for slot labels
slots: [{
  name: 'measure',
  content: [{
    type: 'numeric',
    columnId: '<uuid>',
    datasetId: '<uuid>',
    label: { en: 'Revenue', nl: 'Omzet' }  // Localized label
  }]
}]
```

Ideally, always provide the `language` attribute on the component to ensure localized fields are resolved correctly.

## Timezone

```jsx
<LuzmoVizItemComponent
  timezone="America/New_York"  // IANA timezone
  ...
/>
```

## Complete Example

```jsx
import { LuzmoVizItemComponent } from '@luzmo/react-embed';

function SalesDashboard() {
  const slots = [
    {
      name: 'x-axis',
      content: [{
        type: 'datetime',
        columnId: '550e8400-e29b-41d4-a716-446655440001',
        datasetId: '550e8400-e29b-41d4-a716-446655440000',
        level: 3,  // Month
        label: { en: 'Month' }
      }]
    },
    {
      name: 'measure',
      content: [{
        type: 'numeric',
        columnId: '550e8400-e29b-41d4-a716-446655440002',
        datasetId: '550e8400-e29b-41d4-a716-446655440000',
        aggregationFunc: 'sum',
        format: '$,.0f',
        label: { en: 'Revenue' }
      }]
    }
  ];

  const options = {
    // Title MUST be an object with language keys directly (not a string, not nested!)
    title: { en: 'Monthly Revenue' },
    display: { title: true, legend: false },
    axis: {
      x: { ticksMode: 'ticks' },
      y: { ticksMode: 'gridlines', scale: 'linear' }
    }
  };

  const filters = [{
    condition: 'and',
    filters: [{
      expression: 'last_now',
      parameters: [
        { columnId: '550e8400-e29b-41d4-a716-446655440001', datasetId: '550e8400-e29b-41d4-a716-446655440000' },
        { unit: 3, quantity: 11 }  // Last 12 months
      ]
    }]
  }];

  return (
    <LuzmoVizItemComponent
      appServer="https://app.luzmo.com"
      apiHost="https://api.luzmo.com"
      authKey={process.env.LUZMO_EMBED_KEY}
      authToken={process.env.LUZMO_EMBED_TOKEN}
      type="column-chart"
      slots={slots}
      options={options}
      filters={filters}
      language="en"
      timezone="UTC"
    />
  );
}
```

## Dashboard Embedding Component

For embedding complete Luzmo dashboards (not code-first), use `LuzmoDashboardComponent`:

```jsx
import { LuzmoDashboardComponent } from '@luzmo/react-embed';

<LuzmoDashboardComponent
  dashboardId="<dashboard-uuid>"
  authKey="<embed-key>"
  authToken="<embed-token>"
  appServer="https://app.luzmo.com"
  apiHost="https://api.luzmo.com"
  language="en"
  timezoneId="America/New_York"
  screenMode="auto"
  editMode="view"  // 'view', 'editLimited', or 'editFull'
/>
```

Key properties:
- `dashboardId`: Dashboard UUID to embed
- `itemId`: Optional - embed single item from dashboard
- `screenMode`: 'auto', 'mobile', 'tablet', 'desktop', 'largeScreen', 'fixed'
- `editMode`: 'view' (default), 'editLimited', 'editFull' (for embedded editor)

Full reference: https://developer.luzmo.com/guide/embedding--component-api-reference

## Luzmo IQ Components

Luzmo IQ provides AI-powered natural language data exploration.

### IQ Chat Component

Full chat interface for data questions:

```jsx
import { LuzmoIQChatComponent } from '@luzmo/react-embed';

<LuzmoIQChatComponent
  authKey="<embed-key>"
  authToken="<embed-token>"
  appServer="https://app.luzmo.com"
  apiHost="https://api.luzmo.com"
/>
```

### IQ Answer Component

Display AI-generated chart responses:

```jsx
import { LuzmoIQAnswerComponent } from '@luzmo/react-embed';

<LuzmoIQAnswerComponent
  authKey="<embed-key>"
  authToken="<embed-token>"
  question="What are the top 5 products by revenue?"
/>
```

Note: IQ requires a separate license - contact Luzmo for access.

Full IQ reference: https://developer.luzmo.com/guide/iq--introduction

## Resources

- Flex Introduction: https://developer.luzmo.com/guide/flex--introduction
- Component API Reference: https://developer.luzmo.com/guide/flex--component-api-reference
- Chart Documentation: https://developer.luzmo.com/guide/flex--chart-docs
- Individual Chart Docs: https://developer.luzmo.com/flex/charts/{chart-type}
- Flex Examples: https://developer.luzmo.com/flex/examples/adaptive-charts
- Dashboard Embedding: https://developer.luzmo.com/guide/embedding--component-api-reference
- Luzmo IQ: https://developer.luzmo.com/guide/iq--introduction
- JSON Schemas (v0.1.97): https://developer.luzmo.com/assets/json-schemas-dereferenced/0.1.97/
- Academy AI Search: `POST https://ai-knowledge-base.luzmo.com/ask-question` with `{"question": "query", "stream": true}`