@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/Chart/ChartComposables.tsx

@@ -0,0 +1,121 @@
+import { Box, Paper, Typography, useTheme } from '@mui/material';
+import React from 'react';
+import { Legend, ResponsiveContainer, Tooltip } from 'recharts';
+
+/**
+ * Raw chart composables (Squire's ChartConfig pattern, MUI-themed): a
+ * responsive container plus themed tooltip/legend content renderers. The
+ * prop-driven `Chart` uses these internally; consumers building bespoke
+ * Recharts compositions can reuse them directly.
+ */
+
+/** Recharts' Tooltip/Legend re-exported so bespoke compositions can pair them
+ * with the themed content renderers below. */
+export const ChartTooltip = Tooltip;
+export const ChartLegend = Legend;
+
+export interface ChartContainerProps {
+  height: number;
+  width?: number | string;
+  responsive?: boolean;
+  children: React.ReactElement;
+  'data-testid'?: string;
+}
+
+/** Responsive wrapper for a Recharts chart element. */
+export const ChartContainer: React.FC<ChartContainerProps> = ({
+  height,
+  width = '100%',
+  responsive = true,
+  children,
+  'data-testid': dataTestId,
+}) => {
+  if (!responsive) {
+    return (
+      <Box sx={{ width, height }} data-testid={dataTestId}>
+        {children}
+      </Box>
+    );
+  }
+  return (
+    <ResponsiveContainer width="100%" height={height} data-testid={dataTestId}>
+      {children}
+    </ResponsiveContainer>
+  );
+};
+
+interface TooltipEntry {
+  name?: string | number;
+  value?: string | number;
+  color?: string;
+}
+
+export interface ChartTooltipContentProps {
+  active?: boolean;
+  label?: string | number;
+  payload?: TooltipEntry[];
+  /** Formats numeric values (e.g. centavos → BRL). */
+  valueFormatter?: (value: number) => string;
+}
+
+/** Theme-aware tooltip content (light/dark correct, semantic colors only). */
+export const ChartTooltipContent: React.FC<ChartTooltipContentProps> = ({
+  active,
+  label,
+  payload,
+  valueFormatter,
+}) => {
+  const theme = useTheme();
+  if (!active || !payload || payload.length === 0) return null;
+  const formatValue = (value: TooltipEntry['value']): string | number => {
+    if (typeof value === 'number' && valueFormatter) return valueFormatter(value);
+    return value ?? '';
+  };
+  return (
+    <Paper elevation={4} sx={{ px: 1.5, py: 1, border: `1px solid ${theme.palette.divider}` }}>
+      {label !== undefined && label !== '' && (
+        <Typography variant="caption" sx={{ color: 'text.secondary', display: 'block', mb: 0.5 }}>
+          {label}
+        </Typography>
+      )}
+      {payload.map((entry, index) => (
+        <Box key={index} sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+          <Box
+            component="span"
+            sx={{ width: 10, height: 10, borderRadius: '2px', backgroundColor: entry.color, flexShrink: 0 }}
+          />
+          <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+            {entry.name}
+          </Typography>
+          <Typography variant="body2" sx={{ ml: 'auto', fontWeight: 600 }}>
+            {formatValue(entry.value)}
+          </Typography>
+        </Box>
+      ))}
+    </Paper>
+  );
+};
+
+export interface ChartLegendContentProps {
+  payload?: Array<{ value?: string | number; color?: string }>;
+}
+
+/** Theme-aware legend content matching the tooltip's swatch styling. */
+export const ChartLegendContent: React.FC<ChartLegendContentProps> = ({ payload }) => {
+  if (!payload || payload.length === 0) return null;
+  return (
+    <Box sx={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: 2, pt: 1 }}>
+      {payload.map((entry, index) => (
+        <Box key={index} sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+          <Box
+            component="span"
+            sx={{ width: 10, height: 10, borderRadius: '2px', backgroundColor: entry.color, flexShrink: 0 }}
+          />
+          <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+            {entry.value}
+          </Typography>
+        </Box>
+      ))}
+    </Box>
+  );
+};

package/src/components/data-display/Chart/ChartSpec.types.ts

@@ -0,0 +1,70 @@
+/**
+ * JSON-serializable chart specification — the declarative surface of the raw
+ * chart library. A `ChartSpec` plus plain data rows fully describes a rendered
+ * chart, so specs can be persisted, transmitted and authored by report
+ * builders or LLMs without touching component code. Colors are semantic theme
+ * tokens (never raw hex) so light/dark rendering stays correct.
+ */
+
+/** Built-in chart types. New types can be added via the renderer registry. */
+export type ChartSpecType = 'line' | 'bar' | 'area' | 'pie' | 'donut';
+
+/**
+ * Semantic color token resolved against the MUI palette at render time.
+ * Specs must not carry raw color values.
+ */
+export type ChartSemanticColor =
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'warning'
+  | 'error'
+  | 'info';
+
+/**
+ * Number formatting applied to tooltip values and the y axis.
+ * `brl` treats values as integer centavos (the repo-wide money convention)
+ * and renders them as reais, e.g. `123456` → `R$ 1.234,56`.
+ * `percent` treats values as fractions, e.g. `0.153` → `15,3%`.
+ */
+export type ChartNumberFormat = 'brl' | 'percent' | 'compact' | 'integer' | 'decimal';
+
+export interface ChartSpecSeries {
+  /** Row property holding this series' value. */
+  key: string;
+  /** Legend/tooltip label; defaults to `key`. */
+  label?: string;
+  /** Semantic color token; defaults to cycling the spec's color scheme. */
+  color?: ChartSemanticColor;
+}
+
+export interface ChartSpecAxis {
+  /** Row property plotted on the category (x) axis — for pie/donut, the slice name. */
+  key: string;
+  label?: string;
+}
+
+export interface ChartSpec {
+  type: ChartSpecType;
+  title?: string;
+  subtitle?: string;
+  xAxis: ChartSpecAxis;
+  yAxis?: { label?: string };
+  /** At least one series. Pie/donut charts read slice values from the first series. */
+  series: ChartSpecSeries[];
+  /** Stack cartesian series instead of grouping them side by side. */
+  stacked?: boolean;
+  /** Show the legend (default true). */
+  legend?: boolean;
+  /** Show the tooltip (default true). */
+  tooltip?: boolean;
+  numberFormat?: ChartNumberFormat;
+  /** Palette cycled across series without an explicit color. */
+  colorScheme?: ChartSemanticColor[];
+  /** Smooth (monotone) lines/areas (default true). */
+  curved?: boolean;
+  /** Chart height in px; defaults to the host component's size. */
+  height?: number;
+  /** Center label rendered inside a donut chart. */
+  centerLabel?: string | { label: string; value: string | number };
+}

package/src/components/data-display/Chart/SpecChart.stories.tsx

@@ -0,0 +1,150 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { SpecChart } from './SpecChart';
+import type { ChartSpec } from './ChartSpec.types';
+
+const meta: Meta<typeof SpecChart> = {
+  title: 'DataDisplay/SpecChart',
+  component: SpecChart,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Renders a chart from a JSON-serializable ChartSpec plus plain data rows. ' +
+          'The spec API is layered over the prop-driven Chart — same implementation, ' +
+          'declarative surface for report builders and LLM authoring.',
+      },
+    },
+  },
+  tags: ['autodocs', 'component:Chart'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const salesByDay = [
+  { day: 'Seg', total: 125000, perdas: 4500 },
+  { day: 'Ter', total: 98000, perdas: 1200 },
+  { day: 'Qua', total: 143500, perdas: 0 },
+  { day: 'Qui', total: 110200, perdas: 7300 },
+  { day: 'Sex', total: 189900, perdas: 2100 },
+];
+
+const paymentMethods = [
+  { method: 'PIX', total: 420000 },
+  { method: 'Cartão', total: 310000 },
+  { method: 'Garçom', total: 86000 },
+];
+
+const lineSpec: ChartSpec = {
+  type: 'line',
+  title: 'Vendas por dia',
+  subtitle: 'Receita líquida (BRL)',
+  xAxis: { key: 'day' },
+  series: [{ key: 'total', label: 'Total', color: 'primary' }],
+  numberFormat: 'brl',
+};
+
+export const Line: Story = {
+  args: { spec: lineSpec, data: salesByDay },
+};
+
+export const StackedBars: Story = {
+  args: {
+    spec: {
+      type: 'bar',
+      title: 'Vendas vs perdas',
+      xAxis: { key: 'day' },
+      series: [
+        { key: 'total', label: 'Vendas', color: 'primary' },
+        { key: 'perdas', label: 'Perdas', color: 'error' },
+      ],
+      stacked: true,
+      numberFormat: 'brl',
+    },
+    data: salesByDay,
+  },
+};
+
+export const Area: Story = {
+  args: {
+    spec: { ...lineSpec, type: 'area', title: 'Tendência de vendas' },
+    data: salesByDay,
+  },
+};
+
+export const Pie: Story = {
+  args: {
+    spec: {
+      type: 'pie',
+      title: 'Formas de pagamento',
+      xAxis: { key: 'method' },
+      series: [{ key: 'total' }],
+      numberFormat: 'brl',
+    },
+    data: paymentMethods,
+  },
+};
+
+export const Donut: Story = {
+  args: {
+    spec: {
+      type: 'donut',
+      title: 'Formas de pagamento',
+      xAxis: { key: 'method' },
+      series: [{ key: 'total' }],
+      numberFormat: 'brl',
+      centerLabel: { label: 'Total', value: 'R$ 8.160' },
+    },
+    data: paymentMethods,
+  },
+};
+
+export const PercentFormat: Story = {
+  args: {
+    spec: {
+      type: 'bar',
+      title: 'Margem por dia',
+      xAxis: { key: 'day' },
+      series: [{ key: 'margin', label: 'Margem', color: 'success' }],
+      numberFormat: 'percent',
+      legend: false,
+    },
+    data: salesByDay.map((row) => ({ day: row.day, margin: row.total > 0 ? 0.2 + row.perdas / row.total : 0 })),
+  },
+};
+
+export const CustomColorScheme: Story = {
+  args: {
+    spec: {
+      ...lineSpec,
+      type: 'bar',
+      title: 'Esquema de cores custom',
+      series: [
+        { key: 'total', label: 'Total' },
+        { key: 'perdas', label: 'Perdas' },
+      ],
+      colorScheme: ['info', 'warning'],
+    },
+    data: salesByDay,
+  },
+};
+
+export const FromJsonString: Story = {
+  render: () => {
+    const json =
+      '{"type":"area","title":"Spec vinda de JSON","xAxis":{"key":"day"},' +
+      '"series":[{"key":"total","label":"Total","color":"secondary"}],"numberFormat":"compact"}';
+    return <SpecChart spec={JSON.parse(json) as ChartSpec} data={salesByDay} />;
+  },
+};
+
+export const Loading: Story = {
+  args: { spec: lineSpec, data: [], loading: true },
+};
+
+export const Empty: Story = {
+  args: { spec: { ...lineSpec, title: 'Sem dados' }, data: [] },
+};

package/src/components/data-display/Chart/SpecChart.test.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+
+import { SpecChart } from './SpecChart';
+
+const meta: Meta<typeof SpecChart> = {
+  title: 'DataDisplay/SpecChart/Tests',
+  component: SpecChart,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs', 'test', 'component:Chart'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const data = [
+  { day: 'Seg', total: 125000 },
+  { day: 'Ter', total: 98000 },
+];
+
+export const RendersFromSpec: Story = {
+  args: {
+    spec: {
+      type: 'bar',
+      title: 'Spec Render',
+      xAxis: { key: 'day' },
+      series: [{ key: 'total', label: 'Total', color: 'primary' }],
+      numberFormat: 'brl',
+    },
+    data,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId('spec-chart')).toBeInTheDocument();
+    await expect(canvas.getByText('Spec Render')).toBeInTheDocument();
+  },
+};
+
+export const DonutCenterLabel: Story = {
+  args: {
+    spec: {
+      type: 'donut',
+      xAxis: { key: 'method' },
+      series: [{ key: 'total' }],
+      centerLabel: { label: 'Total', value: 'R$ 100' },
+    },
+    data: [
+      { method: 'PIX', total: 60 },
+      { method: 'Cartão', total: 40 },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId('spec-chart')).toBeInTheDocument();
+  },
+};

package/src/components/data-display/Chart/SpecChart.tsx

@@ -0,0 +1,53 @@
+import { useTheme } from '@mui/material';
+import React from 'react';
+
+import { Chart } from './Chart';
+import type { ChartDataPoint } from './Chart.types';
+import type { ChartSemanticColor, ChartSpec } from './ChartSpec.types';
+import { CHART_SEMANTIC_COLORS, specToChartProps } from './chart-spec';
+
+export interface SpecChartProps {
+  /** Validated spec — parse untrusted JSON with `parseChartSpec` first. */
+  spec: ChartSpec;
+  data: ChartDataPoint[];
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  loading?: boolean;
+  className?: string;
+  onClick?: (point: ChartDataPoint) => void;
+  'data-testid'?: string;
+}
+
+/**
+ * Renders a chart from a JSON-serializable {@link ChartSpec} plus plain data
+ * rows. Layered over the prop-driven `Chart` (one implementation); semantic
+ * color tokens resolve against the active MUI theme at render time.
+ */
+export const SpecChart: React.FC<SpecChartProps> = ({
+  spec,
+  data,
+  size,
+  loading,
+  className,
+  onClick,
+  'data-testid': dataTestId = 'spec-chart',
+}) => {
+  const theme = useTheme();
+  const chartProps = React.useMemo(() => {
+    const scheme: readonly ChartSemanticColor[] =
+      spec.colorScheme && spec.colorScheme.length > 0 ? spec.colorScheme : CHART_SEMANTIC_COLORS;
+    const resolveColor = (token: ChartSemanticColor | undefined, index: number): string =>
+      theme.palette[token ?? scheme[index % scheme.length] ?? 'primary'].main;
+    return specToChartProps(spec, data, { resolveColor });
+  }, [spec, data, theme]);
+
+  return (
+    <Chart
+      {...chartProps}
+      size={size}
+      loading={loading}
+      className={className}
+      onClick={onClick}
+      data-testid={dataTestId}
+    />
+  );
+};

package/src/components/data-display/Chart/__tests__/SpecChart.test.tsx

@@ -0,0 +1,60 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { parseChartSpec } from '../chart-spec';
+import { SpecChart } from '../SpecChart';
+
+const json = JSON.stringify({
+  type: 'bar',
+  title: 'Vendas por dia',
+  subtitle: 'Últimos 7 dias',
+  xAxis: { key: 'day' },
+  series: [
+    { key: 'total', label: 'Total', color: 'primary' },
+    { key: 'perdas', label: 'Perdas', color: 'error' },
+  ],
+  numberFormat: 'brl',
+});
+
+const data = [
+  { day: 'seg', total: 1200, perdas: 100 },
+  { day: 'ter', total: 3400, perdas: 0 },
+];
+
+describe('SpecChart', () => {
+  it('renders a chart from a pure JSON spec plus data rows', () => {
+    render(<SpecChart spec={parseChartSpec(JSON.parse(json))} data={data} />);
+    expect(screen.getByTestId('spec-chart')).toBeInTheDocument();
+    expect(screen.getByText('Vendas por dia')).toBeInTheDocument();
+    expect(screen.getByText('Últimos 7 dias')).toBeInTheDocument();
+  });
+
+  it('renders pie specs', () => {
+    render(
+      <SpecChart
+        spec={parseChartSpec({
+          type: 'pie',
+          xAxis: { key: 'method' },
+          series: [{ key: 'total' }],
+        })}
+        data={[
+          { method: 'PIX', total: 700 },
+          { method: 'Cartão', total: 300 },
+        ]}
+      />,
+    );
+    expect(screen.getByTestId('spec-chart')).toBeInTheDocument();
+  });
+
+  it('shows the loading state', () => {
+    render(
+      <SpecChart
+        spec={parseChartSpec({ type: 'line', xAxis: { key: 'x' }, series: [{ key: 'y' }] })}
+        data={[]}
+        loading
+      />,
+    );
+    expect(screen.getByTestId('spec-chart-loading')).toBeInTheDocument();
+  });
+});

package/src/components/data-display/Chart/__tests__/chart-format.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import { chartValueFormatter, formatChartValue } from '../chart-format';
+
+describe('formatChartValue', () => {
+  it('formats brl from integer centavos', () => {
+    const formatted = formatChartValue(123456, 'brl');
+    expect(formatted).toContain('R$');
+    expect(formatted).toContain('1.234,56');
+  });
+
+  it('formats negative centavos', () => {
+    expect(formatChartValue(-500, 'brl')).toContain('5,00');
+  });
+
+  it('formats percent from a fraction', () => {
+    expect(formatChartValue(0.153, 'percent')).toBe('15,3%');
+  });
+
+  it('formats compact values', () => {
+    expect(formatChartValue(1500, 'compact')).toContain('1,5');
+  });
+
+  it('formats integers without decimals', () => {
+    expect(formatChartValue(1234.56, 'integer')).toBe('1.235');
+  });
+
+  it('defaults to decimal formatting', () => {
+    expect(formatChartValue(1234.567)).toBe('1.234,57');
+  });
+
+  it('renders non-finite values as an empty string', () => {
+    expect(formatChartValue(Number.NaN, 'brl')).toBe('');
+    expect(formatChartValue(Number.POSITIVE_INFINITY)).toBe('');
+  });
+});
+
+describe('chartValueFormatter', () => {
+  it('curries the format', () => {
+    const format = chartValueFormatter('brl');
+    expect(format(100)).toContain('1,00');
+  });
+});

package/src/components/data-display/Chart/__tests__/chart-spec.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ChartSpec } from '../ChartSpec.types';
+import { ChartSpecError, parseChartSpec, specToChartProps } from '../chart-spec';
+import {
+  getRegisteredChartSpecTypes,
+  registerChartSpecRenderer,
+  type ChartSpecRenderContext,
+} from '../chart-spec-registry';
+
+const ctx: ChartSpecRenderContext = {
+  resolveColor: (token, index) => `${token ?? 'auto'}-${index}`,
+};
+
+const lineSpec: ChartSpec = {
+  type: 'line',
+  title: 'Vendas',
+  xAxis: { key: 'day' },
+  series: [{ key: 'total', label: 'Total', color: 'primary' }, { key: 'count' }],
+  numberFormat: 'brl',
+};
+
+describe('parseChartSpec', () => {
+  it('accepts a valid spec round-tripped through JSON', () => {
+    const parsed = parseChartSpec(JSON.parse(JSON.stringify(lineSpec)));
+    expect(parsed.type).toBe('line');
+    expect(parsed.series).toHaveLength(2);
+    expect(parsed.xAxis.key).toBe('day');
+  });
+
+  it('rejects non-objects', () => {
+    expect(() => parseChartSpec('nope')).toThrow(ChartSpecError);
+  });
+
+  it('rejects unknown chart types and lists registered ones', () => {
+    expect(() => parseChartSpec({ ...lineSpec, type: 'sankey' })).toThrow(/registered chart types/);
+    expect(() => parseChartSpec({ ...lineSpec, type: 'sankey' })).toThrow(/line/);
+  });
+
+  it('rejects a missing xAxis key', () => {
+    expect(() => parseChartSpec({ ...lineSpec, xAxis: {} })).toThrow(/"xAxis"/);
+  });
+
+  it('rejects empty series', () => {
+    expect(() => parseChartSpec({ ...lineSpec, series: [] })).toThrow(/"series"/);
+  });
+
+  it('rejects raw color values with an actionable message', () => {
+    expect(() => parseChartSpec({ ...lineSpec, series: [{ key: 'total', color: '#ff0000' }] })).toThrow(
+      /semantic color token/,
+    );
+  });
+
+  it('rejects invalid number formats', () => {
+    expect(() => parseChartSpec({ ...lineSpec, numberFormat: 'usd' })).toThrow(/"numberFormat"/);
+  });
+
+  it('rejects invalid colorScheme entries', () => {
+    expect(() => parseChartSpec({ ...lineSpec, colorScheme: ['primary', 'magenta'] })).toThrow(
+      /"colorScheme\[1\]"/,
+    );
+  });
+});
+
+describe('specToChartProps', () => {
+  it('maps cartesian specs onto Chart props', () => {
+    const props = specToChartProps(lineSpec, [{ day: 'seg', total: 100, count: 2 }], ctx);
+    expect(props.type).toBe('line');
+    expect(props.xAxisKey).toBe('day');
+    expect(props.series).toEqual([
+      { dataKey: 'total', name: 'Total', color: 'primary-0' },
+      { dataKey: 'count', name: 'count', color: 'auto-1' },
+    ]);
+    expect(props.valueFormatter?.(100)).toContain('1,00');
+  });
+
+  it('honors stacked bars and legend/tooltip toggles', () => {
+    const props = specToChartProps(
+      { ...lineSpec, type: 'bar', stacked: true, legend: false, tooltip: false },
+      [],
+      ctx,
+    );
+    expect(props.type).toBe('bar');
+    expect(props.stacked).toBe(true);
+    expect(props.showLegend).toBe(false);
+    expect(props.showTooltip).toBe(false);
+  });
+
+  it('renders donut as pie with an inner radius and center label', () => {
+    const props = specToChartProps(
+      {
+        type: 'donut',
+        xAxis: { key: 'method' },
+        series: [{ key: 'total' }],
+        centerLabel: { label: 'Total', value: 'R$ 10' },
+      },
+      [],
+      ctx,
+    );
+    expect(props.type).toBe('pie');
+    expect(props.innerRadius).toBeGreaterThan(0);
+    expect(props.centerLabel).toEqual({ label: 'Total', value: 'R$ 10' });
+  });
+
+  it('supports registering new chart types without touching consumers', () => {
+    registerChartSpecRenderer('sparkline', (spec) => ({
+      type: 'line',
+      series: spec.series.map((s) => ({ dataKey: s.key })),
+    }));
+    expect(getRegisteredChartSpecTypes()).toContain('sparkline');
+    const spec = parseChartSpec({
+      type: 'sparkline',
+      xAxis: { key: 'x' },
+      series: [{ key: 'y' }],
+    });
+    const props = specToChartProps(spec, [], ctx);
+    expect(props.type).toBe('line');
+  });
+});