Skip to content

plugin-charts.mdx

Latest commit

 

History

History
327 lines (266 loc) · 9.31 KB

plugin-charts.mdx

File metadata and controls

327 lines (266 loc) · 9.31 KB
Raw
title Plugin Charts

import { InteractiveDemo } from '@/app/components/InteractiveDemo'; import { PluginLoader } from '@/app/components/PluginLoader';

Data visualization components powered by Recharts.

Installation

npm install @object-ui/plugin-charts

<PluginLoader plugins={['charts']}>

Interactive Examples

Usage

The plugin provides two chart APIs:

  1. Simple Bar Chart (bar-chart) - Simplified API for basic bar charts
  2. Advanced Charts (chart) - Full-featured API supporting multiple chart types (bar, line, area) and multiple data series

Basic Usage

// Import once in your app entry point
import '@object-ui/plugin-charts'

// Use in schemas
const schema = {
  type: 'bar-chart',
  data: [
    { name: 'Jan', value: 400 },
    { name: 'Feb', value: 300 },
    { name: 'Mar', value: 600 }
  ],
  dataKey: 'value',
  xAxisKey: 'name',
  height: 400
}

Features

  • Bar, line, and area charts
  • Responsive design
  • Customizable colors and styles
  • Lazy-loaded (~540 KB loads only when rendered)

Schema API

{
  type: 'bar-chart',
  data?: Array<Record<string, any>>,  // Chart data
  dataKey?: string,                    // Y-axis data key
  xAxisKey?: string,                   // X-axis label key
  height?: number,                     // Chart height
  color?: string,                      // Bar color
  className?: string                   // Tailwind classes
}

BarChartSchema

Declared by @object-ui/plugin-charts (packages/plugin-charts/src/types.ts). It extends BaseSchema, so the shared component properties are available on a bar-chart node as well as the ones below.

Property Type Default Description
data Array of objects [] Array of data objects to visualize
dataKey string 'value' Key in data objects for Y-axis values
xAxisKey string 'name' Key in data objects for X-axis labels
height number 400 Chart height in pixels
color string '#8884d8' Primary color for bars/lines
className string '' Additional Tailwind CSS classes

Chart Types

The plugin provides two different chart components:

Simple Bar Chart (bar-chart)

For basic single-series bar charts, use the simplified bar-chart type:

const schema = {
  type: 'bar-chart',
  data: [
    { month: 'Jan', sales: 400 },
    { month: 'Feb', sales: 300 },
    { month: 'Mar', sales: 600 }
  ],
  dataKey: 'sales',
  xAxisKey: 'month',
  color: '#3b82f6',
  height: 300
}

Advanced Charts (chart)

For multi-series charts or line/area charts, use the advanced chart type with the chartType property:

Bar Chart
const schema = {
  type: 'chart',
  chartType: 'bar',
  data: [
    { month: 'Jan', sales: 400, target: 350 },
    { month: 'Feb', sales: 300, target: 400 },
    { month: 'Mar', sales: 600, target: 550 }
  ],
  xAxisKey: 'month',
  series: [
    { dataKey: 'sales' },
    { dataKey: 'target' }
  ],
  config: {
    sales: { label: 'Sales', color: '#3b82f6' },
    target: { label: 'Target', color: '#10b981' }
  }
}
Line Chart
const schema = {
  type: 'chart',
  chartType: 'line',
  data: [
    { date: '2024-01', users: 120 },
    { date: '2024-02', users: 180 },
    { date: '2024-03', users: 250 }
  ],
  xAxisKey: 'date',
  series: [
    { dataKey: 'users' }
  ],
  config: {
    users: { label: 'Users', color: '#8884d8' }
  }
}
Area Chart
const schema = {
  type: 'chart',
  chartType: 'area',
  data: [
    { time: '9:00', value: 20 },
    { time: '10:00', value: 35 },
    { time: '11:00', value: 45 }
  ],
  xAxisKey: 'time',
  series: [
    { dataKey: 'value' }
  ],
  config: {
    value: { label: 'Value', color: '#10b981' }
  }
}
Per-series options

Each series entry names the column it plots (dataKey, or the spec spelling name) and may carry the presentation keys the renderer reads — the same keys as @objectstack/spec's ChartSeries:

Key Type Effect
label string or inline locale map Legend / tooltip name; defaults to the column key.
type 'bar' | 'line' | 'area' Per-series family override — a combo chart is a series disagreeing with the chart's chartType.
color string Series colour; wins over the positional palette.
stack string Stack group id — series sharing one id stack together.
yAxis 'left' | 'right' Which y-axis the series binds to, on a chart that declares a second y-axis.
variant 'primary' | 'comparison' comparison draws the muted period-over-period overlay; primary (the default) is the normal treatment.
dashArray string SVG stroke-dasharray, e.g. "4 4" for a dashed line. Today the renderer applies it only on a variant: 'comparison' series and only on a mark that has a stroke to dash — a line or area mark (the chart's chartType, or a per-series type override), where it overrides the overlay's default "4 4"; a comparison bar or scatter mark takes opacity only and drops the dash, and on a primary series of any family it is read and unused.
opacity number Stroke and fill opacity override — any finite number (the spec bounds it to 0–1). Today the renderer applies it only on a variant: 'comparison' series, where it overrides the overlay's per-family default on every mark family — the fill of a bar or scatter mark, the stroke of a line mark, both on an area mark; on a primary series it is read and unused.

chartType is not a series key. It is the renderer's internal spelling of type — @objectstack/spec's ChartSeries lists it as an alias — and the validator refuses it by name (Unrecognized key(s) on this chart series: chartType. Did you mean chartType → type?) instead of dropping it silently, which is what it used to do. Write type.

An area chart keeps every key in this example live: stack stacks the two primary areas, and the comparison overlay takes both the dash and the opacity (on a bar chart the overlay would take opacity only).

const schema = {
  type: 'chart',
  chartType: 'area',
  data: [
    { month: 'Jan', revenue: 400, cost: 250, revenue_prev: 360 },
    { month: 'Feb', revenue: 300, cost: 210, revenue_prev: 330 }
  ],
  xAxisKey: 'month',
  series: [
    { name: 'revenue', label: 'Revenue', stack: 'money' },
    { name: 'cost', label: 'Cost', stack: 'money' },
    // '8 4' overrides the overlay's default '4 4' dash; 0.6 lifts its 0.2 fill default (its stroke default is already 0.6)
    { name: 'revenue_prev', label: 'Revenue (previous period)', variant: 'comparison', dashArray: '8 4', opacity: 0.6 }
  ]
}

Examples

Revenue Dashboard

const revenueChart = {
  type: 'bar-chart',
  data: [
    { quarter: 'Q1 2024', revenue: 45000, target: 50000 },
    { quarter: 'Q2 2024', revenue: 52000, target: 50000 },
    { quarter: 'Q3 2024', revenue: 61000, target: 55000 },
    { quarter: 'Q4 2024', revenue: 58000, target: 60000 }
  ],
  dataKey: 'revenue',
  xAxisKey: 'quarter',
  height: 400,
  color: '#059669',
  className: 'rounded-lg shadow-md'
}

User Growth Chart

const growthChart = {
  type: 'chart',
  chartType: 'line',
  data: [
    { month: 'Jan', users: 1200, active: 980 },
    { month: 'Feb', users: 1450, active: 1150 },
    { month: 'Mar', users: 1680, active: 1380 },
    { month: 'Apr', users: 1920, active: 1620 }
  ],
  xAxisKey: 'month',
  series: [
    { dataKey: 'users' },
    { dataKey: 'active' }
  ],
  config: {
    users: { label: 'Total Users', color: '#8884d8' },
    active: { label: 'Active Users', color: '#82ca9d' }
  }
}

Bundle Size

The plugin uses lazy loading to optimize bundle size:

  • Initial load: ~0.2 KB (entry point)
  • Lazy chunk: ~541 KB minified (~136 KB gzipped)
  • Loads only when rendered

Without lazy loading, this would add 541 KB to your main bundle. With lazy loading, it's loaded only when charts are displayed.

Customization

Custom Colors

{/* doc-snippet: fragment — shape excerpt; salesData is the reader's own rows */}

const schema = {
  type: 'bar-chart',
  data: salesData,
  color: '#f59e0b', // Amber color
  className: 'bg-white p-4 rounded-lg'
}

Responsive Height

{/* doc-snippet: fragment — shape excerpt; metricsData is the reader's own rows */}

const schema = {
  type: 'chart',
  chartType: 'line',
  data: metricsData,
  xAxisKey: 'date',
  series: [{ dataKey: 'value' }],
  config: {
    value: { label: 'Metrics', color: '#8884d8' }
  },
  className: 'h-64 sm:h-96 lg:h-[500px]'
}

TypeScript Support

import type { BarChartSchema } from '@object-ui/plugin-charts'

const chartSchema: BarChartSchema = {
  type: 'bar-chart',
  data: [
    { name: 'Product A', value: 400 },
    { name: 'Product B', value: 300 }
  ],
  dataKey: 'value',
  xAxisKey: 'name',
  height: 400
}

Related Documentation