From ae420246c83b16c3b24624945d987e38f18e021e Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Sun, 12 Apr 2026 19:37:27 +0200 Subject: [PATCH] docs: update COMPONENT_GUIDE for ThemedChart migration --- COMPONENT_GUIDE.md | 81 ++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 43 deletions(-) diff --git a/COMPONENT_GUIDE.md b/COMPONENT_GUIDE.md index b8b15e2..66231f2 100644 --- a/COMPONENT_GUIDE.md +++ b/COMPONENT_GUIDE.md @@ -54,8 +54,8 @@ ### "I need to display data" - Key metrics → **StatCard** (with optional sparkline/trend) - Tabular data → **DataTable** (sortable, paginated) -- Time series → **LineChart**, **AreaChart** -- Categorical comparison → **BarChart** +- Time series → **ThemedChart** with `` or `` +- Categorical comparison → **ThemedChart** with `` - Inline trend → **Sparkline** - Advanced charts (treemap, radar, heatmap, pie, etc.) → **Recharts** with `rechartsTheme` (see [Charting Strategy](#charting-strategy)) - Event log → **EventFeed** @@ -138,7 +138,7 @@ FormField wraps any input (Input, Textarea, Select, RadioGroup, etc.) ### KPI dashboard ``` Row of StatCard components (each with optional Sparkline and trend) -Below: charts (AreaChart, LineChart, BarChart) +Below: charts (ThemedChart with Line, Area, or Bar) ``` ### Master/detail management pattern @@ -175,57 +175,54 @@ StatCard strip (top, recalculates per scope) → GroupCard grid (2-col for all, full-width for single app) Each GroupCard: header (app name + count) + meta (TPS, routes) + instance rows Instance rows: StatusDot + name + Badge + metrics - Single instance: expanded with LineChart panels + Single instance: expanded with ThemedChart panels → EventFeed (bottom, filtered by scope) URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/:instanceId ``` ## Charting Strategy -The design system includes built-in **AreaChart**, **BarChart**, **LineChart**, and **Sparkline** components for standard use cases. For advanced chart types (treemap, radar, heatmap, pie, sankey, etc.), consuming apps should use **Recharts** directly with the design system's theme preset for visual consistency. +The design system provides a **ThemedChart** wrapper component that applies consistent styling to Recharts charts. Recharts is bundled as a dependency — consumers do not need to install it separately. -**Recharts is the app's dependency, not the design system's.** The design system only exports a theme config object. - -### Setup in consuming app - -```bash -npm install recharts -``` - -### Usage with theme preset +### Usage ```tsx -import { rechartsTheme, CHART_COLORS } from '@cameleer/design-system' -import { - ResponsiveContainer, LineChart, Line, - CartesianGrid, XAxis, YAxis, Tooltip, Legend, -} from 'recharts' +import { ThemedChart, Line, Area, ReferenceLine, CHART_COLORS } from '@cameleer/design-system' - - - - - - - - - - - +const data = metrics.map(m => ({ time: m.timestamp, cpu: m.value * 100 })) + + + + + ``` -### Exports +### ThemedChart Props -| Export | Description | -|--------|-------------| -| `rechartsTheme.cartesianGrid` | Dashed gridlines, subtle stroke | -| `rechartsTheme.xAxis` | Mono font axis ticks, subtle color | -| `rechartsTheme.yAxis` | Mono font axis ticks, no axis line | -| `rechartsTheme.tooltip` | Surface bg, border, shadow, monospace values | -| `rechartsTheme.legend` | Matching text size and color | -| `rechartsTheme.colors` | The 8 `CHART_COLORS` (CSS variables with light/dark support) | +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `data` | `Record[]` | required | Flat array of data objects | +| `height` | `number` | `200` | Chart height in pixels | +| `xDataKey` | `string` | `"time"` | Key for x-axis values | +| `xType` | `'number' \| 'category'` | `"category"` | X-axis scale type | +| `xTickFormatter` | `(value: any) => string` | — | Custom x-axis label formatter | +| `yTickFormatter` | `(value: any) => string` | — | Custom y-axis label formatter | +| `yLabel` | `string` | — | Y-axis label text | +| `children` | `ReactNode` | required | Recharts elements (Line, Area, Bar, etc.) | +| `className` | `string` | — | Container CSS class | + +### Available Recharts Re-exports + +`Line`, `Area`, `Bar`, `ReferenceLine`, `ReferenceArea`, `Legend`, `Brush` + +For chart types not covered (treemap, radar, pie, sankey), import from `recharts` directly and use `rechartsTheme` for consistent styling. + +### Theme Utilities + +| Export | Purpose | +|--------|---------| | `CHART_COLORS` | Array of `var(--chart-1)` through `var(--chart-8)` | -| `ChartSeries` / `DataPoint` | Type interfaces for chart data | +| `rechartsTheme` | Pre-configured prop objects for Recharts sub-components | ## Component Index @@ -234,11 +231,9 @@ import { | Accordion | composite | Multiple collapsible sections, single or multi-open mode | | Alert | primitive | Page-level attention banner with variant colors | | AlertDialog | composite | Confirmation dialog for destructive/important actions | -| AreaChart | composite | Time series visualization with filled area | | Avatar | primitive | User representation with initials and color | | AvatarGroup | composite | Stacked overlapping avatars with overflow count | | Badge | primitive | Labeled status indicator with semantic colors | -| BarChart | composite | Categorical data comparison, optional stacking | | Breadcrumb | composite | Navigation path showing current location | | Button | primitive | Action trigger (primary, secondary, danger, ghost) | | ButtonGroup | primitive | Multi-select toggle group with optional colored dot indicators. Props: items (value, label, color?), value (Set), onChange | @@ -266,7 +261,7 @@ import { | KeyboardHint | primitive | Keyboard shortcut display | | KpiStrip | composite | Horizontal row of KPI cards with colored left border, trend, subtitle, optional sparkline | | Label | primitive | Form label with optional required asterisk | -| LineChart | composite | Time series line visualization | +| ThemedChart | composite | Recharts wrapper with themed axes, grid, and tooltip | | LogViewer | composite | Scrollable log output with timestamped, severity-colored monospace entries | | MenuItem | composite | Sidebar navigation item with health/count | | Modal | composite | Generic dialog overlay with backdrop |