xertica-ui 2.1.2 → 2.1.4

package/docs/components/chart.md

@@ -4,6 +4,8 @@
 
 Xertica UI provides a `ChartContainer` wrapper and related components built on top of **Recharts** for theme-aware, token-driven chart rendering. The chart system uses a `ChartConfig` object to define series labels and colors via CSS variables, ensuring full dark-mode support without hard-coded hex values.
 
+The library ships **11 dashboard-ready chart wrappers** that handle loading, empty, and error states automatically, so feature layers only need to pass `data`, `isLoading`, `error`, and `onRetry`.
+
 ---
 
 ## Exports
@@ -23,7 +25,13 @@ Xertica UI provides a `ChartContainer` wrapper and related components built on t
 | `InteractiveTimeSeriesChart` | Area time-series chart with metric tabs and period select |
 | `ComboMetricChart` | Composed bar, line, and area chart for mixed metrics |
 | `DonutBreakdownChart` | Donut/pie breakdown chart with interactive segment focus |
+| `SparklineChart` | Compact inline area/line chart for KPI cards |
+| `RadarMetricChart` | Multi-dimensional radar/spider chart |
+| `PieMetricChart` | Proportional pie chart with optional donut, labels, and exploded slice |
+| `RadialBarMetricChart` | Circular progress rings (radial bar chart) |
+| `GaugeChart` | Semicircle gauge with needle, thresholds, and color zones |
 | `ChartConfig` | TypeScript type for chart configuration |
+| `GaugeChartThreshold` | TypeScript type for gauge color zone thresholds |
 
 ---
 
@@ -42,6 +50,8 @@ npm install recharts
 3. Reference colors in chart elements using `fill="var(--color-yourKey)"`.
 4. The container automatically injects CSS variables for light and dark themes.
 
+Dashboard-ready wrappers (`DashboardBarChart`, `RadarMetricChart`, etc.) build the config internally — you only need to pass `data` and `series`/`nameKey`/`valueKey`.
+
 ---
 
 ## ChartConfig Type
@@ -59,9 +69,24 @@ type ChartConfig = {
 
 ---
 
+## Color Tokens
+
+Chart colors use `--chart-1` through `--chart-8` CSS tokens. These are theme-aware and automatically switch between light and dark mode.
+
+```tsx
+// In ChartConfig
+{ revenue: { label: 'Revenue', color: 'var(--chart-1)' } }
+
+// In dashboard-ready wrappers — pass as array or per-key map
+colors={['var(--chart-1)', 'var(--chart-2)']}
+colors={{ revenue: 'var(--chart-1)', expenses: 'var(--chart-5)' }}
+```
+
+---
+
 ## Examples
 
-### Bar Chart
+### Bar Chart (low-level)
 
 ```tsx
 import {
@@ -72,13 +97,7 @@ import {
   ChartLegendContent,
   type ChartConfig,
 } from 'xertica-ui/ui';
-import {
-  BarChart,
-  Bar,
-  XAxis,
-  YAxis,
-  CartesianGrid,
-} from 'recharts';
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid } from 'recharts';
 import { Card, CardHeader, CardTitle, CardContent } from 'xertica-ui/ui';
 
 const chartConfig: ChartConfig = {
@@ -112,7 +131,7 @@ const data = [
 </Card>
 ```
 
-### Line Chart
+### Line Chart (low-level)
 
 ```tsx
 const chartConfig: ChartConfig = {
@@ -168,7 +187,6 @@ const data = [
     data={data}
     indexKey="date"
     config={config}
-    colors={['var(--chart-1)', 'var(--chart-4)']}
     series={[
       { key: 'revenue', label: 'Revenue' },
       { key: 'pipeline', label: 'Pipeline' },
@@ -180,22 +198,8 @@ const data = [
   <DonutBreakdownChart data={segments} config={segmentConfig} />
 </ChartCard>
 
-<ChartCard title="Pipeline Trend">
-  <DashboardLineChart data={trendData} config={config} />
-</ChartCard>
-
 <DashboardBarChart data={data} indexKey="date" config={config} stacked />
 
-<DashboardLineChart
-  data={data}
-  indexKey="date"
-  config={config}
-  colors={{
-    revenue: 'var(--chart-1)',
-    pipeline: 'var(--chart-4)',
-  }}
-/>
-
 <HorizontalBarChart
   data={[
     { segment: 'Enterprise', revenue: 7600 },
@@ -217,25 +221,318 @@ const data = [
     { key: 'conversion', type: 'line' },
   ]}
 />
+```
 
-<DonutBreakdownChart
-  data={[
-    { name: 'enterprise', value: 52 },
-    { name: 'midmarket', value: 31 },
-  ]}
-  config={{
-    enterprise: { label: 'Enterprise', color: 'var(--chart-1)' },
-    midmarket: { label: 'Mid-market', color: 'var(--chart-4)' },
-  }}
-  colors={['var(--chart-1)', 'var(--chart-4)']}
-  centerValue="83"
-  centerLabel="Accounts"
+---
+
+### Radar Chart
+
+Multi-dimensional comparison across categorical axes. Use a single series for a simple spider chart, or multiple series for side-by-side comparison.
+
+```tsx
+import { RadarMetricChart, ChartCard } from 'xertica-ui/ui';
+
+const data = [
+  { skill: 'Speed',    frontend: 80, backend: 60 },
+  { skill: 'Quality',  frontend: 90, backend: 85 },
+  { skill: 'Coverage', frontend: 70, backend: 95 },
+  { skill: 'Security', frontend: 65, backend: 88 },
+  { skill: 'Perf',     frontend: 75, backend: 72 },
+];
+
+// Single series — filled polygon
+<ChartCard title="Frontend Skills">
+  <RadarMetricChart
+    data={data}
+    labelKey="skill"
+    series={[{ key: 'frontend', label: 'Frontend' }]}
+    filled
+    fillOpacity={0.3}
+  />
+</ChartCard>
+
+// Multi-series comparison
+<ChartCard title="Team Comparison">
+  <RadarMetricChart
+    data={data}
+    labelKey="skill"
+    series={[
+      { key: 'frontend', label: 'Frontend' },
+      { key: 'backend',  label: 'Backend' },
+    ]}
+    filled={false}
+    showDots
+    showLegend
+  />
+</ChartCard>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DashboardChartDatum[]` | — | Data array; each item is one axis point |
+| `labelKey` | `string` | — | Key used as the axis label |
+| `series` | `DashboardChartSeries[]` | — | Series to render (one `<Radar>` per entry) |
+| `colors` | `DashboardChartColors` | auto | Override colors per key or as ordered array |
+| `filled` | `boolean` | `true` | Fill the radar polygon |
+| `fillOpacity` | `number` | `0.25` | Fill opacity when `filled` is true |
+| `showDots` | `boolean` | `false` | Show dots on each axis point |
+| `showGrid` | `boolean` | `true` | Show polar grid lines |
+| `showLegend` | `boolean` | auto | Show legend (auto-shown when multiple series) |
+| `valueFormatter` | `(v: number) => string` | — | Format axis tick and tooltip values |
+| + state props | — | — | `isLoading`, `error`, `onRetry`, etc. |
+
+---
+
+### Pie Chart
+
+Proportional slices. Supports donut mode (`innerRadius > 0`), percentage labels, and an exploded (offset) slice for emphasis.
+
+```tsx
+import { PieMetricChart, ChartCard } from 'xertica-ui/ui';
+
+const data = [
+  { segment: 'Enterprise', value: 52 },
+  { segment: 'Mid-market', value: 31 },
+  { segment: 'SMB',        value: 17 },
+];
+
+// Simple pie
+<ChartCard title="Revenue Mix">
+  <PieMetricChart
+    data={data}
+    nameKey="segment"
+    valueKey="value"
+    showLabels
+  />
+</ChartCard>
+
+// Donut variant
+<ChartCard title="Revenue Mix (Donut)">
+  <PieMetricChart
+    data={data}
+    nameKey="segment"
+    valueKey="value"
+    innerRadius="55%"
+    outerRadius="80%"
+  />
+</ChartCard>
+
+// Exploded slice (highlight index 0)
+<ChartCard title="Top Segment">
+  <PieMetricChart
+    data={data}
+    nameKey="segment"
+    valueKey="value"
+    explodeIndex={0}
+    explodeOffset={14}
+  />
+</ChartCard>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DashboardChartDatum[]` | — | Data array; each item is one slice |
+| `nameKey` | `string` | — | Key used as the slice name/label |
+| `valueKey` | `string` | — | Key used as the slice value |
+| `colors` | `DashboardChartColors` | auto | Override colors as ordered array or per-name map |
+| `outerRadius` | `number \| string` | `"80%"` | Outer radius of the pie |
+| `innerRadius` | `number \| string` | `0` | Inner radius — set > 0 for donut |
+| `showLabels` | `boolean` | `false` | Show percentage labels on slices |
+| `showLegend` | `boolean` | `true` | Show the legend |
+| `explodeIndex` | `number` | — | Index of the slice to offset outward |
+| `explodeOffset` | `number` | `12` | Offset distance in px for the exploded slice |
+| `valueFormatter` | `(v: number) => string` | — | Format tooltip values |
+| + state props | — | — | `isLoading`, `error`, `onRetry`, etc. |
+
+---
+
+### Radial Bar Chart
+
+Circular progress rings. Each data item renders as a concentric arc. Useful for showing multiple metrics as percentage completion.
+
+```tsx
+import { RadialBarMetricChart, ChartCard } from 'xertica-ui/ui';
+
+const data = [
+  { name: 'CPU',     value: 72 },
+  { name: 'Memory',  value: 58 },
+  { name: 'Storage', value: 41 },
+  { name: 'Network', value: 89 },
+];
+
+// Full-circle rings (default)
+<ChartCard title="Resource Usage">
+  <RadialBarMetricChart
+    data={data}
+    dataKey="value"
+    nameKey="name"
+    valueFormatter={(v) => `${v}%`}
+  />
+</ChartCard>
+
+// Semi-circle layout
+<ChartCard title="Resource Usage (Semi)">
+  <RadialBarMetricChart
+    data={data}
+    dataKey="value"
+    nameKey="name"
+    startAngle={180}
+    endAngle={0}
+    innerRadius="20%"
+    outerRadius="90%"
+  />
+</ChartCard>
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DashboardChartDatum[]` | — | Data array; each item is one ring |
+| `dataKey` | `string` | `"value"` | Key used as the bar value |
+| `nameKey` | `string` | `"name"` | Key used as the bar label |
+| `colors` | `DashboardChartColors` | auto | Override colors as ordered array or per-name map |
+| `innerRadius` | `number \| string` | `"30%"` | Inner radius of the radial bar |
+| `outerRadius` | `number \| string` | `"100%"` | Outer radius of the radial bar |
+| `startAngle` | `number` | `90` | Start angle in degrees (90 = top) |
+| `endAngle` | `number` | `-270` | End angle in degrees (-270 = full circle) |
+| `showBackground` | `boolean` | `true` | Show background track behind each bar |
+| `showLegend` | `boolean` | `true` | Show the legend below the chart |
+| `valueFormatter` | `(v: number) => string` | — | Format tooltip and legend values |
+| + state props | — | — | `isLoading`, `error`, `onRetry`, etc. |
+
+---
+
+### Gauge Chart
+
+Semicircle gauge with a needle indicator and optional color zones (thresholds). Implemented as pure SVG — no Recharts dependency.
+
+```tsx
+import { GaugeChart, ChartCard, type GaugeChartThreshold } from 'xertica-ui/ui';
+
+// Simple percentage gauge
+<ChartCard title="CPU Usage">
+  <div className="flex justify-center py-4">
+    <GaugeChart value={72} label="CPU" />
+  </div>
+</ChartCard>
+
+// With color thresholds
+const thresholds: GaugeChartThreshold[] = [
+  { value: 40,  color: 'var(--chart-2)', label: 'Healthy' },
+  { value: 70,  color: 'var(--chart-3)', label: 'Warning' },
+  { value: 100, color: 'var(--chart-5)', label: 'Critical' },
+];
+
+<ChartCard title="Memory Usage">
+  <div className="flex justify-center py-4">
+    <GaugeChart
+      value={85}
+      label="Memory"
+      thresholds={thresholds}
+    />
+  </div>
+</ChartCard>
+
+// Custom range and formatter
+<GaugeChart
+  value={1250}
+  min={0}
+  max={2000}
+  label="Requests/s"
+  valueFormatter={(value) => `${value.toLocaleString()} rps`}
+  showNeedle={false}
 />
 ```
 
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — | Current value (must be within `[min, max]`) |
+| `min` | `number` | `0` | Minimum value |
+| `max` | `number` | `100` | Maximum value |
+| `thresholds` | `GaugeChartThreshold[]` | — | Color zones evaluated in order; first zone where `value >= current %` wins |
+| `label` | `React.ReactNode` | — | Label shown below the center value |
+| `valueFormatter` | `(value: number, percent: number) => string` | — | Format the center value text (default: shows `%`) |
+| `showNeedle` | `boolean` | `true` | Show the needle indicator |
+| `className` | `string` | — | Additional CSS classes |
+
+**`GaugeChartThreshold` type:**
+
+```typescript
+interface GaugeChartThreshold {
+  value: number;   // Upper bound of this zone (0–100)
+  color: string;   // Color for this zone (use CSS var tokens)
+  label?: string;  // Optional label shown in the legend
+}
+```
+
+**Infrastructure dashboard example:**
+
+```tsx
+const metrics = [
+  { label: 'CPU',     value: 72 },
+  { label: 'Memory',  value: 85 },
+  { label: 'Storage', value: 41 },
+];
+
+const thresholds: GaugeChartThreshold[] = [
+  { value: 60,  color: 'var(--chart-2)', label: 'OK' },
+  { value: 80,  color: 'var(--chart-3)', label: 'Warning' },
+  { value: 100, color: 'var(--chart-5)', label: 'Critical' },
+];
+
+<div className="grid grid-cols-3 gap-4">
+  {metrics.map((m) => (
+    <ChartCard key={m.label} title={m.label}>
+      <div className="flex justify-center py-2">
+        <GaugeChart
+          value={m.value}
+          label={m.label}
+          thresholds={thresholds}
+        />
+      </div>
+    </ChartCard>
+  ))}
+</div>
+```
+
+---
+
+### Sparkline Chart
+
+Compact inline chart for KPI cards and metric summaries. Renders as a minimal area or line chart with no axes or labels.
+
+```tsx
+import { SparklineChart } from 'xertica-ui/ui';
+
+// Filled area sparkline (default)
+<SparklineChart
+  data={[{ v: 10 }, { v: 25 }, { v: 18 }, { v: 40 }, { v: 35 }]}
+  dataKey="v"
+  color="var(--chart-1)"
+  filled
+/>
+
+// Line-only sparkline
+<SparklineChart
+  data={weeklyData}
+  dataKey="sessions"
+  color="var(--chart-2)"
+  filled={false}
+/>
+```
+
+---
+
 ### Empty and Connection States
 
-Dashboard-ready chart wrappers handle loading, empty data, and connection errors without forcing each feature to duplicate presentation logic. In an FSD architecture, keep fetching and error mapping in the feature/model layer, then pass the state into the UI component.
+All dashboard-ready chart wrappers handle loading, empty data, and connection errors without forcing each feature to duplicate presentation logic. In an FSD architecture, keep fetching and error mapping in the feature/model layer, then pass the state into the UI component.
 
 ```tsx
 <DashboardLineChart
@@ -249,9 +546,23 @@ Dashboard-ready chart wrappers handle loading, empty data, and connection errors
   errorTitle="Connection error"
   errorDescription="Unable to load analytics data."
 />
+
+// State props work on all dashboard-ready wrappers:
+<RadarMetricChart
+  data={skillData}
+  labelKey="skill"
+  series={[{ key: 'score', label: 'Score' }]}
+  isLoading={isLoading}
+  error={error}
+  onRetry={refetch}
+/>
 ```
 
-State props are available on `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, and `DonutBreakdownChart`.
+State props (`isLoading`, `error`, `onRetry`, `retryLabel`, `emptyTitle`, `emptyDescription`, `errorTitle`, `errorDescription`, `loadingLabel`, `stateClassName`) are available on: `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `RadarMetricChart`, `PieMetricChart`, and `RadialBarMetricChart`.
+
+> `GaugeChart` does not extend `ChartStateProps` — it is a pure display component with no async state.
+
+---
 
 ### Stacked Bar Chart
 
@@ -317,10 +628,14 @@ Bar-based dashboard charts support `barSize="sm" | "md" | "lg" | "xl"` or a nume
 - `ChartContainer` already wraps `ResponsiveContainer width="100%" height="100%"` — do not add another one.
 - Set height on `ChartContainer` via `className="h-[300px]"` — this sizes the container, not the Recharts elements.
 - Import all base Recharts components (`BarChart`, `Bar`, `Line`, etc.) directly from `recharts` — they are not re-exported by `xertica-ui`.
-- For dashboard-ready charts, prefer `ChartCard` plus `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, or `DonutBreakdownChart` before hand-assembling Recharts primitives.
+- For dashboard-ready charts, prefer `ChartCard` plus a dashboard-ready wrapper before hand-assembling Recharts primitives.
 - In FSD apps, keep data fetching in the feature/model layer and pass `data`, `isLoading`, `error`, and `onRetry` into chart wrappers.
 - Use `barSize` to control bar thickness. Do not use a chart wrapper prop to control graph width; layout width belongs to the parent grid/container.
 - When using `stacked`, order your `series` array so the visually topmost series is last — it will automatically receive the rounded top corners.
+- `RadarMetricChart`, `PieMetricChart`, and `RadialBarMetricChart` build their `ChartConfig` internally from the `series`/`nameKey` data — you do not need to pass a `config` prop.
+- `GaugeChart` is a pure SVG component — it does not use `ChartContainer` or Recharts. Wrap it in a `div` with `flex justify-center` to control its width.
+- For `GaugeChart` thresholds, use `--chart-*` CSS tokens for colors so they remain theme-aware. Never use raw hex values.
+- `RadialBarMetricChart` renders its legend as HTML below the chart (not inside the SVG) — this is intentional to avoid Recharts polar chart legend positioning issues.
 
 ---
 

package/docs/components/code-block.md

@@ -0,0 +1,108 @@
+# CodeBlock
+
+A syntax-highlighted code display component with a one-click copy button. Designed for use inside AI chat messages and documentation panels.
+
+---
+
+## Import
+
+```tsx
+import { CodeBlock } from 'xertica-ui/assistant';
+```
+
+---
+
+## Basic Usage
+
+```tsx
+<CodeBlock
+  language="typescript"
+  code={`function greet(name: string): string {
+  return \`Hello, \${name}!\`;
+}`}
+/>
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | _(required)_ | The source code string to display |
+| `language` | `string` | `'text'` | Language identifier for syntax highlighting (e.g. `'typescript'`, `'python'`, `'bash'`) |
+| `className` | `string` | — | Additional CSS classes for the outer container |
+
+---
+
+## Features
+
+### Syntax Highlighting
+
+Uses `react-syntax-highlighter` (Prism engine) with a custom theme built on Xertica UI design tokens:
+
+- **Keywords / operators**: `var(--chart-1)` (primary accent)
+- **Strings**: `var(--chart-2)` (green-toned)
+- **Numbers / booleans**: `var(--chart-5)` (amber-toned)
+- **Properties / attributes**: `var(--chart-4)` (blue-toned)
+- **Comments**: `var(--muted-foreground)` (subdued)
+- **Background**: transparent (inherits from parent card)
+
+The theme automatically adapts to light and dark mode via CSS custom properties.
+
+### Copy Button
+
+A copy-to-clipboard button appears in the top-right corner of the code block. After clicking:
+- The icon changes from `Copy` to `Check` for 2 seconds
+- The code string is written to the clipboard via the Clipboard API
+
+### Supported Languages
+
+Any language supported by Prism.js is valid. Common examples:
+
+```
+typescript  javascript  tsx  jsx
+python      bash        sql  json
+css         html        yaml markdown
+```
+
+---
+
+## Usage in AI Context
+
+`CodeBlock` is used internally by `XerticaAssistant` to render code snippets returned by the AI. When the assistant response contains a fenced code block (` ```language `), it is automatically rendered as a `CodeBlock`.
+
+To render code blocks in a standalone context:
+
+```tsx
+import { CodeBlock } from 'xertica-ui/assistant';
+
+function AiResponse({ content }: { content: string }) {
+  // Parse code blocks from markdown and render them
+  return (
+    <CodeBlock
+      language="python"
+      code="print('Hello from AI')"
+    />
+  );
+}
+```
+
+---
+
+## Design Notes
+
+- The component uses `font-mono` (CSS variable `--font-mono`) for the code font
+- Font size is fixed at `0.875rem` (14px) for readability in narrow panels
+- Line height is `1.6` for comfortable reading
+- Tab size is 2 spaces
+- Horizontal overflow scrolls within the block (no line wrapping)
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Always provide `language`**: Without it, syntax highlighting falls back to plain text. Use the correct language identifier (e.g. `'typescript'` not `'ts'`, `'javascript'` not `'js'`).
+> - **Do not wrap in `<pre>` or `<code>`**: `CodeBlock` renders its own `<pre>` via `react-syntax-highlighter`. Wrapping it will break the layout.
+> - **Optimized for narrow panels**: This component is designed for the AI Assistant sidebar (~400px). For full-page code display, consider adding `className="w-full"`.