# Plugin Charts Data visualization components powered by Recharts. ## Installation [#installation] ```bash npm install @object-ui/plugin-charts ``` ## Interactive Examples [#interactive-examples] ## Usage [#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 [#basic-usage] ```tsx // 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 [#features] * **Bar, line, and area charts** * **Responsive design** * **Customizable colors and styles** * **Lazy-loaded** (\~540 KB loads only when rendered) ## Schema API [#schema-api] ```plaintext { type: 'bar-chart', data?: Array>, // 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 [#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 [#chart-types] The plugin provides two different chart components: ### Simple Bar Chart (bar-chart) [#simple-bar-chart-bar-chart] For basic single-series bar charts, use the simplified `bar-chart` type: ```tsx 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) [#advanced-charts-chart] For multi-series charts or line/area charts, use the advanced `chart` type with the `chartType` property: ##### Bar Chart [#bar-chart] ```tsx 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 [#line-chart] ```tsx 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 [#area-chart] ```tsx 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 [#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). ```tsx 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 [#examples] ### Revenue Dashboard [#revenue-dashboard] ```tsx 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 [#user-growth-chart] ```tsx 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 [#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 [#customization] ### Custom Colors [#custom-colors] {/* doc-snippet: fragment — shape excerpt; `salesData` is the reader's own rows */} ```tsx const schema = { type: 'bar-chart', data: salesData, color: '#f59e0b', // Amber color className: 'bg-white p-4 rounded-lg' } ``` ### Responsive Height [#responsive-height] {/* doc-snippet: fragment — shape excerpt; `metricsData` is the reader's own rows */} ```tsx 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 [#typescript-support] ```ts 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 [#related-documentation] * [Plugin System Overview](/docs/guide/plugins) * [Lazy-Loaded Plugins Architecture](/docs/guide/plugins#lazy-loading-architecture) * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-charts)