@12-apps/ui 1.0.0 → 1.3.1

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

@@ -0,0 +1,26 @@
+import type { ChartNumberFormat } from './ChartSpec.types';
+
+const formatters: Record<ChartNumberFormat, Intl.NumberFormat> = {
+  brl: new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }),
+  percent: new Intl.NumberFormat('pt-BR', { style: 'percent', maximumFractionDigits: 1 }),
+  compact: new Intl.NumberFormat('pt-BR', { notation: 'compact', maximumFractionDigits: 1 }),
+  integer: new Intl.NumberFormat('pt-BR', { maximumFractionDigits: 0 }),
+  decimal: new Intl.NumberFormat('pt-BR', { maximumFractionDigits: 2 }),
+};
+
+/**
+ * Format a chart value with one of the serializable number formats.
+ * `brl` expects integer centavos (repo-wide money convention); `percent`
+ * expects a fraction (0.15 → "15%"). Non-finite values render as an empty
+ * string so a null-ish row never draws "NaN" into a tooltip or axis.
+ */
+export function formatChartValue(value: number, format: ChartNumberFormat = 'decimal'): string {
+  if (!Number.isFinite(value)) return '';
+  if (format === 'brl') return formatters.brl.format(value / 100);
+  return formatters[format].format(value);
+}
+
+/** Curried {@link formatChartValue}, memo-friendly for tooltip/axis props. */
+export function chartValueFormatter(format?: ChartNumberFormat): (value: number) => string {
+  return (value: number) => formatChartValue(value, format);
+}

package/src/components/data-display/Chart/chart-internals.ts

@@ -0,0 +1,148 @@
+import { alpha, type Theme } from '@mui/material';
+import type { CSSProperties } from 'react';
+
+import type { ChartProps, ChartSeries } from './Chart.types';
+
+/**
+ * Non-JSX internals of the prop-driven Chart: size/variant styling, palette
+ * resolution and series auto-detection. Split from Chart.tsx to keep every
+ * function inside the repo's complexity budget.
+ */
+
+export interface SizeStyles {
+  height: number;
+  fontSize: string;
+}
+
+const SIZE_PRESETS: Record<NonNullable<ChartProps['size']>, SizeStyles> = {
+  xs: { height: 200, fontSize: '0.75rem' },
+  sm: { height: 300, fontSize: '0.875rem' },
+  md: { height: 400, fontSize: '1rem' },
+  lg: { height: 500, fontSize: '1.125rem' },
+  xl: { height: 600, fontSize: '1.25rem' },
+};
+
+export function getSizeStyles(size: ChartProps['size'], height?: number): SizeStyles {
+  const preset = SIZE_PRESETS[size ?? 'md'] ?? SIZE_PRESETS.md;
+  return { height: height ?? preset.height, fontSize: preset.fontSize };
+}
+
+const NEON_PALETTE = ['#00ffff', '#ff00ff', '#ffff00', '#00ff00', '#ff0080', '#8000ff'];
+
+export function getDefaultColors(theme: Theme, variant: ChartProps['variant'], colors?: string[]): string[] {
+  if (colors) return colors;
+  if (variant === 'neon') return NEON_PALETTE;
+  return [
+    theme.palette.primary.main,
+    theme.palette.secondary.main,
+    theme.palette.success.main,
+    theme.palette.warning.main,
+    theme.palette.error.main,
+    theme.palette.info.main,
+  ];
+}
+
+type SxStyles = Record<string, unknown>;
+
+interface VariantOptions {
+  variant: NonNullable<ChartProps['variant']>;
+  color: NonNullable<ChartProps['color']>;
+  glow: boolean;
+  pulse: boolean;
+  glass: boolean;
+  gradient: boolean;
+  disabled: boolean;
+}
+
+function effectStyles(theme: Theme, options: VariantOptions): SxStyles {
+  const accent = theme.palette[options.color].main;
+  const glow = options.glow ? { boxShadow: `0 0 30px ${alpha(accent, 0.4)}` } : {};
+  const pulse = options.pulse
+    ? {
+        animation: 'pulse 2s infinite',
+        '@keyframes pulse': {
+          '0%': { boxShadow: `0 0 0 0 ${alpha(accent, 0.4)}` },
+          '70%': { boxShadow: `0 0 0 20px ${alpha(accent, 0)}` },
+          '100%': { boxShadow: `0 0 0 0 ${alpha(accent, 0)}` },
+        },
+      }
+    : {};
+  return { ...glow, ...pulse };
+}
+
+function variantSurface(theme: Theme, options: VariantOptions): SxStyles {
+  switch (options.variant) {
+    case 'glass':
+      return {
+        backgroundColor: alpha(theme.palette.background.paper, options.glass ? 0.1 : 0.9),
+        backdropFilter: 'blur(20px)',
+        border: `1px solid ${alpha(theme.palette.divider, 0.1)}`,
+      };
+    case 'gradient':
+      return {
+        background: options.gradient
+          ? `linear-gradient(135deg, ${alpha(theme.palette[options.color].light, 0.05)}, ${alpha(theme.palette[options.color].dark, 0.05)})`
+          : theme.palette.background.paper,
+      };
+    case 'elevated':
+      return { boxShadow: theme.shadows[4] };
+    case 'minimal':
+      return { border: 'none', backgroundColor: 'transparent' };
+    case 'neon':
+      return {
+        backgroundColor: '#000',
+        border: `1px solid ${alpha('#00ffff', 0.3)}`,
+        '& .recharts-cartesian-grid-horizontal line, & .recharts-cartesian-grid-vertical line': {
+          stroke: alpha('#00ffff', 0.1),
+        },
+      };
+    default:
+      return { backgroundColor: theme.palette.background.paper };
+  }
+}
+
+export function getVariantStyles(theme: Theme, options: VariantOptions): SxStyles {
+  return {
+    borderRadius: theme.spacing(1),
+    transition: theme.transitions.create(['all'], {
+      duration: theme.transitions.duration.standard,
+    }),
+    opacity: options.disabled ? 0.5 : 1,
+    pointerEvents: options.disabled ? ('none' as const) : ('auto' as const),
+    ...effectStyles(theme, options),
+    ...variantSurface(theme, options),
+  };
+}
+
+/** Explicit series, or one series per non-axis key found in the first row. */
+export function resolveSeries(
+  data: ChartProps['data'],
+  series: ChartSeries[] | undefined,
+  xAxisKey: string,
+  palette: string[],
+): ChartSeries[] {
+  if (series) return series;
+  if (data.length === 0) return [];
+  return Object.keys(data[0] ?? {})
+    .filter((key) => key !== xAxisKey)
+    .map((key, index) => ({
+      dataKey: key,
+      name: key,
+      color: palette[index % palette.length],
+    }));
+}
+
+interface AxisTextStyles {
+  axisStyle: CSSProperties;
+  gridStroke: string;
+}
+
+export function getAxisStyles(theme: Theme, variant: ChartProps['variant'], fontSize: string): AxisTextStyles {
+  return {
+    axisStyle: {
+      fontSize,
+      fill: variant === 'neon' ? '#00ffff' : theme.palette.text.secondary,
+    },
+    gridStroke: variant === 'neon' ? alpha('#00ffff', 0.1) : theme.palette.divider,
+  };
+}

package/src/components/data-display/Chart/chart-renderers.tsx

@@ -0,0 +1,338 @@
+import type { Theme } from '@mui/material';
+import React from 'react';
+import {
+  Area,
+  AreaChart,
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Cell,
+  ComposedChart,
+  Legend,
+  Line,
+  LineChart,
+  Pie,
+  PieChart,
+  PolarAngleAxis,
+  PolarGrid,
+  PolarRadiusAxis,
+  Radar,
+  RadarChart,
+  Scatter,
+  ScatterChart,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+
+import type { ChartDataPoint, ChartProps, ChartSeries } from './Chart.types';
+import { ChartLegendContent, ChartTooltipContent } from './ChartComposables';
+import {
+  getAxisStyles,
+  getDefaultColors,
+  getSizeStyles,
+  resolveSeries,
+  type SizeStyles,
+} from './chart-internals';
+
+/**
+ * Per-type Recharts renderers for the prop-driven Chart, dispatched from a
+ * registry keyed by `ChartProps['type']`. Each renderer reads a prepared
+ * {@link ChartRenderContext} so every function stays small.
+ */
+
+interface ChartRenderContext {
+  props: ChartProps;
+  theme: Theme;
+  sizeStyles: SizeStyles;
+  chartColors: string[];
+  chartSeries: ChartSeries[];
+  strokeType: 'monotone' | 'linear';
+  axisStyle: React.CSSProperties;
+  gridStroke: string;
+  animationDuration: number;
+  commonProps: {
+    data: ChartDataPoint[];
+    margin: { top?: number; right?: number; bottom?: number; left?: number };
+    onClick: (payload: unknown) => void;
+  };
+}
+
+function chartExtras(ctx: ChartRenderContext): React.ReactNode[] {
+  const { props } = ctx;
+  const nodes: React.ReactNode[] = [];
+  if (props.showTooltip !== false) {
+    nodes.push(
+      <Tooltip key="tooltip" content={<ChartTooltipContent valueFormatter={props.valueFormatter} />} />,
+    );
+  }
+  if (props.showLegend !== false) {
+    nodes.push(<Legend key="legend" content={<ChartLegendContent />} />);
+  }
+  return nodes;
+}
+
+function cartesianAxes(ctx: ChartRenderContext): React.ReactNode[] {
+  const { props } = ctx;
+  const nodes: React.ReactNode[] = [];
+  if (props.showCartesianGrid !== false) {
+    nodes.push(<CartesianGrid key="grid" strokeDasharray="3 3" stroke={ctx.gridStroke} />);
+  }
+  nodes.push(
+    <XAxis key="x" dataKey={props.xAxisKey ?? 'name'} style={ctx.axisStyle} label={props.xAxisLabel} />,
+    <YAxis key="y" style={ctx.axisStyle} label={props.yAxisLabel} tickFormatter={props.valueFormatter} />,
+  );
+  return nodes;
+}
+
+function renderLine(ctx: ChartRenderContext): React.ReactElement {
+  return (
+    <LineChart {...ctx.commonProps}>
+      {cartesianAxes(ctx)}
+      {chartExtras(ctx)}
+      {ctx.chartSeries.map((s, index) => (
+        <Line
+          key={s.dataKey}
+          type={ctx.strokeType}
+          dataKey={s.dataKey}
+          name={s.name}
+          stroke={s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          strokeWidth={s.strokeWidth ?? 2}
+          dot={s.dot !== false}
+          activeDot={s.activeDot !== false ? { r: 8 } : false}
+          animationDuration={ctx.animationDuration}
+        />
+      ))}
+    </LineChart>
+  );
+}
+
+function renderBar(ctx: ChartRenderContext): React.ReactElement {
+  return (
+    <BarChart {...ctx.commonProps}>
+      {cartesianAxes(ctx)}
+      {chartExtras(ctx)}
+      {ctx.chartSeries.map((s, index) => (
+        <Bar
+          key={s.dataKey}
+          dataKey={s.dataKey}
+          name={s.name}
+          fill={s.fill ?? s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          stackId={ctx.props.stacked ? 'stack' : undefined}
+          animationDuration={ctx.animationDuration}
+        />
+      ))}
+    </BarChart>
+  );
+}
+
+function renderArea(ctx: ChartRenderContext): React.ReactElement {
+  return (
+    <AreaChart {...ctx.commonProps}>
+      {cartesianAxes(ctx)}
+      {chartExtras(ctx)}
+      {ctx.chartSeries.map((s, index) => (
+        <Area
+          key={s.dataKey}
+          type={ctx.strokeType}
+          dataKey={s.dataKey}
+          name={s.name}
+          stroke={s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          fill={s.fill ?? s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          fillOpacity={s.fillOpacity ?? 0.6}
+          stackId={ctx.props.stacked ? 'stack' : undefined}
+          animationDuration={ctx.animationDuration}
+        />
+      ))}
+    </AreaChart>
+  );
+}
+
+function pieCenterLabel(ctx: ChartRenderContext): React.ReactNode {
+  const { centerLabel } = ctx.props;
+  const innerRadius = ctx.props.innerRadius ?? 0;
+  if (!centerLabel || innerRadius <= 0) return null;
+  const fill = ctx.props.variant === 'neon' ? '#00ffff' : ctx.theme.palette.text.primary;
+  return (
+    <text
+      x="50%"
+      y="50%"
+      textAnchor="middle"
+      dominantBaseline="middle"
+      style={{ fontSize: ctx.sizeStyles.fontSize, fill, fontWeight: 600 }}
+    >
+      {typeof centerLabel === 'string' ? (
+        centerLabel
+      ) : (
+        <>
+          <tspan
+            x="50%"
+            dy="-0.6em"
+            style={{ fontSize: '0.875em', fontWeight: 500, fill: ctx.theme.palette.text.secondary }}
+          >
+            {centerLabel.label}
+          </tspan>
+          <tspan x="50%" dy="1.4em" style={{ fontSize: '1.5em', fontWeight: 700 }}>
+            {centerLabel.value}
+          </tspan>
+        </>
+      )}
+    </text>
+  );
+}
+
+function renderPie(ctx: ChartRenderContext): React.ReactElement {
+  const { props } = ctx;
+  return (
+    <PieChart>
+      {chartExtras(ctx)}
+      <Pie
+        data={props.data}
+        dataKey={ctx.chartSeries[0]?.dataKey ?? 'value'}
+        nameKey={props.xAxisKey ?? 'name'}
+        cx="50%"
+        cy="50%"
+        outerRadius={ctx.sizeStyles.height / 3}
+        innerRadius={props.innerRadius ?? 0}
+        fill={ctx.chartColors[0]}
+        label={props.showValues ?? false}
+        animationDuration={ctx.animationDuration}
+      >
+        {props.data.map((entry, index) => (
+          <Cell key={`cell-${index}`} fill={ctx.chartColors[index % ctx.chartColors.length]} />
+        ))}
+      </Pie>
+      {pieCenterLabel(ctx)}
+    </PieChart>
+  );
+}
+
+function renderRadar(ctx: ChartRenderContext): React.ReactElement {
+  return (
+    <RadarChart {...ctx.commonProps}>
+      <PolarGrid stroke={ctx.gridStroke} />
+      <PolarAngleAxis dataKey={ctx.props.xAxisKey ?? 'name'} style={ctx.axisStyle} />
+      <PolarRadiusAxis style={ctx.axisStyle} />
+      {chartExtras(ctx)}
+      {ctx.chartSeries.map((s, index) => (
+        <Radar
+          key={s.dataKey}
+          dataKey={s.dataKey}
+          name={s.name}
+          stroke={s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          fill={s.fill ?? s.color ?? ctx.chartColors[index % ctx.chartColors.length]}
+          fillOpacity={s.fillOpacity ?? 0.6}
+          animationDuration={ctx.animationDuration}
+        />
+      ))}
+    </RadarChart>
+  );
+}
+
+function renderScatter(ctx: ChartRenderContext): React.ReactElement {
+  const { props } = ctx;
+  return (
+    <ScatterChart {...ctx.commonProps}>
+      {props.showCartesianGrid !== false && (
+        <CartesianGrid strokeDasharray="3 3" stroke={ctx.gridStroke} />
+      )}
+      <XAxis dataKey={props.xAxisKey ?? 'name'} style={ctx.axisStyle} label={props.xAxisLabel} />
+      <YAxis dataKey={ctx.chartSeries[0]?.dataKey} style={ctx.axisStyle} label={props.yAxisLabel} />
+      {chartExtras(ctx)}
+      <Scatter
+        name={ctx.chartSeries[0]?.name ?? 'Data'}
+        data={props.data}
+        fill={ctx.chartColors[0]}
+        animationDuration={ctx.animationDuration}
+      />
+    </ScatterChart>
+  );
+}
+
+function composedSeries(ctx: ChartRenderContext, s: ChartSeries, index: number): React.ReactElement {
+  const color = s.color ?? ctx.chartColors[index % ctx.chartColors.length];
+  if (s.type === 'bar') {
+    return (
+      <Bar key={s.dataKey} dataKey={s.dataKey} name={s.name} fill={color} animationDuration={ctx.animationDuration} />
+    );
+  }
+  if (s.type === 'area') {
+    return (
+      <Area
+        key={s.dataKey}
+        type={ctx.strokeType}
+        dataKey={s.dataKey}
+        name={s.name}
+        stroke={color}
+        fill={color}
+        fillOpacity={0.6}
+        animationDuration={ctx.animationDuration}
+      />
+    );
+  }
+  return (
+    <Line
+      key={s.dataKey}
+      type={ctx.strokeType}
+      dataKey={s.dataKey}
+      name={s.name}
+      stroke={color}
+      animationDuration={ctx.animationDuration}
+    />
+  );
+}
+
+function renderComposed(ctx: ChartRenderContext): React.ReactElement {
+  return (
+    <ComposedChart {...ctx.commonProps}>
+      {cartesianAxes(ctx)}
+      {chartExtras(ctx)}
+      {ctx.chartSeries.map((s, index) => composedSeries(ctx, s, index))}
+    </ComposedChart>
+  );
+}
+
+const RENDERERS: Record<string, (ctx: ChartRenderContext) => React.ReactElement> = {
+  line: renderLine,
+  bar: renderBar,
+  area: renderArea,
+  pie: renderPie,
+  radar: renderRadar,
+  scatter: renderScatter,
+  composed: renderComposed,
+};
+
+function buildContext(props: ChartProps, theme: Theme): ChartRenderContext {
+  const sizeStyles = getSizeStyles(props.size, props.height);
+  const chartColors = getDefaultColors(theme, props.variant ?? 'default', props.colors);
+  const { axisStyle, gridStroke } = getAxisStyles(theme, props.variant ?? 'default', sizeStyles.fontSize);
+  const handleChartClick = (payload: unknown): void => {
+    const chartData = payload as { activePayload?: Array<{ payload: ChartDataPoint }> };
+    if (props.onClick && chartData?.activePayload?.[0]) {
+      props.onClick(chartData.activePayload[0].payload);
+    }
+  };
+  return {
+    props,
+    theme,
+    sizeStyles,
+    chartColors,
+    chartSeries: resolveSeries(props.data, props.series, props.xAxisKey ?? 'name', chartColors),
+    strokeType: (props.curved ?? true) ? 'monotone' : 'linear',
+    axisStyle: { ...axisStyle, fontSize: sizeStyles.fontSize },
+    gridStroke,
+    animationDuration: (props.animate ?? true) ? (props.animationDuration ?? 1500) : 0,
+    commonProps: {
+      data: props.data,
+      margin: { top: 20, right: 30, left: 20, bottom: 20, ...props.margin },
+      onClick: handleChartClick,
+    },
+  };
+}
+
+/** Render the Recharts element for the requested chart type. */
+export function renderChartByType(props: ChartProps, theme: Theme): React.ReactElement {
+  const renderer = RENDERERS[props.type ?? 'line'];
+  const ctx = buildContext(props, theme);
+  return renderer ? renderer(ctx) : <></>;
+}

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

@@ -0,0 +1,74 @@
+import type { ChartProps, ChartSeries } from './Chart.types';
+import type { ChartSemanticColor, ChartSpec } from './ChartSpec.types';
+
+/**
+ * Renderer registry — the seam that lets new chart types be added without
+ * touching consumers. A renderer maps a validated spec to the prop fragment
+ * specific to its chart type; shared props (data, axes, legend, tooltip,
+ * formatting) are derived once in `specToChartProps`.
+ */
+
+export interface ChartSpecRenderContext {
+  /**
+   * Resolve a semantic color token to a concrete theme color. `index` is the
+   * series position, used to cycle the spec's color scheme when the series
+   * has no explicit token.
+   */
+  resolveColor: (token: ChartSemanticColor | undefined, index: number) => string;
+}
+
+export type ChartSpecRenderer = (spec: ChartSpec, ctx: ChartSpecRenderContext) => Partial<ChartProps>;
+
+const registry = new Map<string, ChartSpecRenderer>();
+
+export function registerChartSpecRenderer(type: string, renderer: ChartSpecRenderer): void {
+  registry.set(type, renderer);
+}
+
+export function getChartSpecRenderer(type: string): ChartSpecRenderer | undefined {
+  return registry.get(type);
+}
+
+export function getRegisteredChartSpecTypes(): string[] {
+  return [...registry.keys()];
+}
+
+function toChartSeries(spec: ChartSpec, ctx: ChartSpecRenderContext): ChartSeries[] {
+  return spec.series.map((series, index) => ({
+    dataKey: series.key,
+    name: series.label ?? series.key,
+    color: ctx.resolveColor(series.color, index),
+  }));
+}
+
+function cartesianRenderer(chartType: 'line' | 'bar' | 'area'): ChartSpecRenderer {
+  return (spec, ctx) => ({
+    type: chartType,
+    series: toChartSeries(spec, ctx),
+    stacked: spec.stacked ?? false,
+    curved: spec.curved ?? true,
+  });
+}
+
+const pieRenderer: ChartSpecRenderer = (spec, ctx) => ({
+  type: 'pie',
+  series: toChartSeries(spec, ctx),
+  // Slice colors cycle the resolved scheme; the pie renderer reads them from
+  // the `colors` prop rather than per-series colors.
+  colors: spec.series.length
+    ? Array.from({ length: 12 }, (_, index) => ctx.resolveColor(undefined, index))
+    : undefined,
+});
+
+const donutRenderer: ChartSpecRenderer = (spec, ctx) => ({
+  ...pieRenderer(spec, ctx),
+  // Proportional to the pie's outer radius (height / 3 in the Chart renderer).
+  innerRadius: Math.round((spec.height ?? 400) / 6),
+  centerLabel: spec.centerLabel,
+});
+
+registerChartSpecRenderer('line', cartesianRenderer('line'));
+registerChartSpecRenderer('bar', cartesianRenderer('bar'));
+registerChartSpecRenderer('area', cartesianRenderer('area'));
+registerChartSpecRenderer('pie', pieRenderer);
+registerChartSpecRenderer('donut', donutRenderer);