# Chart

Canonical: https://socra.design/charts/chart

The official shadcn Base Chart namespace (ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle) from @socra/web-ui over Recharts v3.

Use chart.* when a surface needs a data visualization from the shared shadcn chart system: chart.ChartContainer owns the config context and sizing, chart.ChartTooltip/ChartTooltipContent the annotated hover surface, chart.ChartLegend/ChartLegendContent the legend row. Pass any recharts chart (BarChart, LineChart, …) as the ChartContainer child.

Status: ready. The live specimen renders the official shadcn Bar Chart - Interactive: a Card with Desktop/Mobile total selectors in the header, 30 daily data points, single active Bar, date-formatted XAxis, ChartTooltip with date labelFormatter, and semantic var(--chart-N) Socra tokens.

Library: @socra/web-ui

## Anatomy

- chart.ChartContainer — the context provider and ResponsiveContainer wrapper; config maps data keys to labels and CSS colors.
- chart.ChartTooltip — the recharts Tooltip, pre-wired to ChartContext; pass ChartTooltipContent as content.
- chart.ChartTooltipContent — the themed tooltip card; renders label and formatted value rows.
- chart.ChartLegend — the recharts Legend, pre-wired to ChartContext; pass ChartLegendContent as content.
- chart.ChartLegendContent — the themed legend row; maps config keys to swatches and labels.
- chart.ChartStyle — the CSS-variable injector; ChartContainer includes it automatically.

## States

- **Rest:** Shows the stable, enabled component without implied activity.
- **Hover:** Adds pointer affordance without moving content or changing meaning.
- **Focus:** Shows the shared visible focus treatment without depending on hover.
- **Pressed:** Acknowledges active input immediately and returns cleanly on release.
- **Selected:** Uses a neutral surface plus native selected semantics when selection applies.
- **Disabled:** Remains legible, unavailable, and absent from misleading interaction feedback.
- **Loading:** Preserves context while honestly identifying work that has not completed.
- **Error:** Places the failure and recovery path beside the action or content that failed.

## Motion

Stable state changes respond immediately. Appearance, expansion, and morphing begin at the triggering origin and use an interruptible spring that can retarget from its live position and velocity. When spatial motion is not meaningful, the component changes without decorative travel.

## Usage

- Define every data key in the ChartContainer config. Config drives color injection and tooltip/legend labels from one source of truth.
- Use chart.ChartTooltipContent and chart.ChartLegendContent as the content renderers. The themed content components apply Socra color tokens automatically without custom styling.
- Import chart primitives (BarChart, Bar, XAxis, …) directly from recharts. ChartContainer accepts any recharts chart child; the namespace only wraps the chrome.

## Avoid

- Do not reach past chart.* into recharts internals for tooltips or legends. The chart namespace owns the recharts binding; raw recharts chrome is unthemed.
- Do not confuse chart.* (shadcn base) with @socra/ui-web-chart (semantic charts.*). @socra/ui-web-chart owns the Socra semantic chart family; @socra/web-ui owns the shadcn base chart namespace.

## Tokens

- `designTokens.color[mode].color.brand.primary`: Primary action role.
- `designTokens.color[mode].color.surface.secondary`: Working surface role.
- `designTokens.color[mode].color.content.primary`: Primary content role.
- `designTokens.spacing.role.contentGap`: Spacing relationship.
- `designTokens.shape.role.control`: Shape relationship.

## Example

```tsx
import { chart } from '@socra/web-ui';
import { BarChart, Bar, XAxis, CartesianGrid } from 'recharts';

const config = {
  desktop: { label: 'Desktop', color: 'var(--chart-1)' },
  mobile:  { label: 'Mobile',  color: 'var(--chart-2)' },
};

<chart.ChartContainer config={config} className="min-h-[200px]">
  <BarChart data={data}>
    <CartesianGrid vertical={false} />
    <XAxis dataKey="month" tickLine={false} axisLine={false} />
    <chart.ChartTooltip content={<chart.ChartTooltipContent />} />
    <chart.ChartLegend content={<chart.ChartLegendContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile"  fill="var(--color-mobile)"  radius={4} />
  </BarChart>
</chart.ChartContainer>
```