@fivem-nui/svelte-components 0.0.0-stage → 1.0.0

package/src/components/data/chart/renderers/line.ts

@@ -0,0 +1,99 @@
+import type { ChartData, ChartOptions } from '../types';
+import type { ChartRenderer, RenderContext } from './base';
+import { drawMessage } from './base';
+import { getColor, colorToRgba } from '../color';
+import { calculateScale, drawGridAndYLabels, DEFAULT_CHART_PADDING } from '../scale';
+
+/**
+ * Renderer for line charts.
+ */
+export class LineChartRenderer implements ChartRenderer {
+  render(context: RenderContext, data: ChartData, options: ChartOptions): void {
+    const { ctx, width, height } = context;
+    const padding = DEFAULT_CHART_PADDING;
+    const chartW = Math.max(10, width - padding.left - padding.right);
+    const chartH = Math.max(10, height - padding.top - padding.bottom);
+
+    const labels = data.labels || [];
+    const datasets = data.datasets.filter((d) => !d.hidden);
+    if (datasets.length === 0) {
+      drawMessage(ctx, width, height, 'All datasets are hidden');
+      return;
+    }
+
+    const scale = calculateScale(datasets, options, chartH, padding.top);
+    drawGridAndYLabels(ctx, padding, chartW, chartH, scale, options);
+
+    const showLabels = options.showLabels !== false;
+    const pointCount = Math.max(labels.length, ...datasets.map((d) => d.data.length), 1);
+    const stepX = pointCount > 1 ? chartW / (pointCount - 1) : chartW / 2;
+
+    if (showLabels) {
+      for (let i = 0; i < pointCount; i++) {
+        if (labels[i]) {
+          const x = padding.left + i * stepX;
+          ctx.fillStyle = '#a1a1aa';
+          ctx.textAlign = 'center';
+          ctx.textBaseline = 'top';
+          ctx.fillText(labels[i], x, padding.top + chartH + 8);
+        }
+      }
+    }
+
+    datasets.forEach((ds, dsIndex) => {
+      const color = getColor(ds.borderColor || ds.backgroundColor, dsIndex);
+      ctx.strokeStyle = color;
+      ctx.lineWidth = Math.max(0, ds.borderWidth ?? 2);
+
+      const segments: { x: number; y: number }[][] = [];
+      let currentSegment: { x: number; y: number }[] = [];
+
+      for (let i = 0; i < pointCount; i++) {
+        const val = ds.data[i];
+        if (val !== null && val !== undefined && Number.isFinite(val)) {
+          const safeVal = Math.max(scale.minVal, Math.min(scale.maxVal, val));
+          const x = padding.left + i * stepX;
+          const y = padding.top + chartH - ((safeVal - scale.minVal) / scale.range) * chartH;
+          currentSegment.push({ x, y });
+        } else {
+          if (currentSegment.length > 0) {
+            segments.push(currentSegment);
+            currentSegment = [];
+          }
+        }
+      }
+      if (currentSegment.length > 0) {
+        segments.push(currentSegment);
+      }
+
+      segments.forEach((segment) => {
+        if (segment.length === 0) return;
+
+        ctx.beginPath();
+        segment.forEach((p, idx) => {
+          if (idx === 0) ctx.moveTo(p.x, p.y);
+          else ctx.lineTo(p.x, p.y);
+        });
+        ctx.stroke();
+
+        // Area fill clipped to baselineY
+        ctx.lineTo(segment[segment.length - 1].x, scale.baselineY);
+        ctx.lineTo(segment[0].x, scale.baselineY);
+        ctx.closePath();
+        ctx.fillStyle = colorToRgba(color, 0.1);
+        ctx.fill();
+
+        // Render point markers
+        ctx.fillStyle = '#ffffff';
+        ctx.strokeStyle = color;
+        ctx.lineWidth = 2;
+        segment.forEach((p) => {
+          ctx.beginPath();
+          ctx.arc(p.x, p.y, 3.5, 0, Math.PI * 2);
+          ctx.fill();
+          ctx.stroke();
+        });
+      });
+    });
+  }
+}

package/src/components/data/chart/renderers/pie.ts

@@ -0,0 +1,66 @@
+import type { ChartData, ChartOptions } from '../types';
+import type { ChartRenderer, RenderContext } from './base';
+import { drawMessage } from './base';
+import { getColor } from '../color';
+
+/**
+ * Renderer for pie and doughnut charts.
+ */
+export class PieChartRenderer implements ChartRenderer {
+  constructor(private readonly isDoughnut: boolean = false) {}
+
+  render(context: RenderContext, data: ChartData, _options: ChartOptions): void {
+    const { ctx, width, height } = context;
+    const cx = width / 2;
+    const cy = height / 2;
+    const radius = Math.max(10, Math.min(width, height) / 2 - 20);
+
+    // Pie chart uses the first visible dataset
+    const dataset = data.datasets.find((d) => !d.hidden) ?? data.datasets[0];
+    if (!dataset || dataset.hidden || !dataset.data || dataset.data.length === 0) {
+      drawMessage(ctx, width, height, 'Dataset is hidden or empty');
+      return;
+    }
+
+    const positiveValues = dataset.data.map((v) =>
+      typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0
+    );
+    const total = positiveValues.reduce((acc, v) => acc + v, 0);
+
+    if (total <= 0) {
+      drawMessage(ctx, width, height, 'No positive values for pie chart');
+      return;
+    }
+
+    let startAngle = -Math.PI / 2;
+    positiveValues.forEach((val, idx) => {
+      if (val <= 0) return;
+
+      const sliceAngle = (val / total) * (Math.PI * 2);
+      const endAngle = startAngle + sliceAngle;
+      const color = getColor(dataset.backgroundColor, idx);
+
+      ctx.fillStyle = color;
+      ctx.beginPath();
+      ctx.moveTo(cx, cy);
+      ctx.arc(cx, cy, radius, startAngle, endAngle);
+      ctx.closePath();
+      ctx.fill();
+
+      ctx.strokeStyle = 'rgba(24, 24, 27, 0.8)';
+      ctx.lineWidth = 2;
+      ctx.stroke();
+
+      startAngle = endAngle;
+    });
+
+    if (this.isDoughnut) {
+      ctx.save();
+      ctx.globalCompositeOperation = 'destination-out';
+      ctx.beginPath();
+      ctx.arc(cx, cy, radius * 0.58, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.restore();
+    }
+  }
+}

package/src/components/data/chart/scale.ts

@@ -0,0 +1,139 @@
+import type { ChartData, ChartOptions } from './types';
+
+export interface ScaleInfo {
+  minVal: number;
+  maxVal: number;
+  range: number;
+  baselineY: number;
+}
+
+export interface ChartPadding {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export const DEFAULT_CHART_PADDING: ChartPadding = {
+  top: 20,
+  right: 20,
+  bottom: 35,
+  left: 45,
+};
+
+/**
+ * Calculates Y axis scale supporting both positive and negative values.
+ */
+export function calculateScale(
+  datasets: ChartData['datasets'],
+  options: ChartOptions,
+  chartH: number,
+  paddingTop: number = DEFAULT_CHART_PADDING.top
+): ScaleInfo {
+  let dataMin = Infinity;
+  let dataMax = -Infinity;
+  let hasValidData = false;
+
+  for (const ds of datasets) {
+    if (ds.hidden) continue;
+    for (const val of ds.data) {
+      if (typeof val === 'number' && Number.isFinite(val)) {
+        hasValidData = true;
+        if (val < dataMin) dataMin = val;
+        if (val > dataMax) dataMax = val;
+      }
+    }
+  }
+
+  if (!hasValidData) {
+    dataMin = 0;
+    dataMax = 10;
+  }
+
+  const userMinValid = typeof options.min === 'number' && Number.isFinite(options.min);
+  const userMaxValid = typeof options.max === 'number' && Number.isFinite(options.max);
+
+  let minVal: number;
+  let maxVal: number;
+
+  if (userMinValid && userMaxValid) {
+    if (options.min! < options.max!) {
+      minVal = options.min!;
+      maxVal = options.max!;
+    } else {
+      console.warn(
+        `[NuiChart] Invalid scale configuration: min (${options.min}) >= max (${options.max}). Falling back to auto range.`
+      );
+      minVal = dataMin < 0 ? Math.floor(dataMin * 1.15) : 0;
+      maxVal = dataMax > 0 ? Math.ceil(dataMax * 1.15) : 10;
+    }
+  } else if (userMinValid) {
+    minVal = options.min!;
+    maxVal = Math.max(minVal + 1, dataMax > 0 ? Math.ceil(dataMax * 1.15) : 10);
+  } else if (userMaxValid) {
+    maxVal = options.max!;
+    minVal = Math.min(maxVal - 1, dataMin < 0 ? Math.floor(dataMin * 1.15) : 0);
+  } else {
+    // Auto scale covering zero
+    minVal = dataMin < 0 ? Math.floor(dataMin * 1.15) : 0;
+    maxVal = dataMax > 0 ? Math.ceil(dataMax * 1.15) : 10;
+  }
+
+  if (minVal >= maxVal) {
+    maxVal = minVal + 10;
+  }
+
+  const range = maxVal - minVal;
+  const rawZeroY = paddingTop + chartH - ((0 - minVal) / range) * chartH;
+  const baselineY = Math.max(paddingTop, Math.min(paddingTop + chartH, rawZeroY));
+
+  return { minVal, maxVal, range, baselineY };
+}
+
+/**
+ * Draws horizontal grid lines, Y axis labels, and highlighted zero baseline.
+ */
+export function drawGridAndYLabels(
+  ctx: CanvasRenderingContext2D,
+  padding: ChartPadding,
+  chartW: number,
+  chartH: number,
+  scale: ScaleInfo,
+  options: ChartOptions
+): void {
+  const showGrid = options.showGrid !== false;
+  const showLabels = options.showLabels !== false;
+  const gridSteps = 4;
+
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.08)';
+  ctx.fillStyle = '#a1a1aa';
+  ctx.font = '11px sans-serif';
+  ctx.textAlign = 'right';
+  ctx.textBaseline = 'middle';
+  ctx.lineWidth = 1;
+
+  for (let i = 0; i <= gridSteps; i++) {
+    const yVal = scale.minVal + (scale.range / gridSteps) * i;
+    const y = padding.top + chartH - ((yVal - scale.minVal) / scale.range) * chartH;
+
+    if (showGrid) {
+      ctx.beginPath();
+      ctx.moveTo(padding.left, y);
+      ctx.lineTo(padding.left + chartW, y);
+      ctx.stroke();
+    }
+
+    if (showLabels) {
+      ctx.fillText(Math.round(yVal).toString(), padding.left - 8, y);
+    }
+  }
+
+  // Highlight zero baseline if range covers both negative and positive values
+  if (scale.minVal < 0 && scale.maxVal > 0) {
+    ctx.strokeStyle = 'rgba(255, 255, 255, 0.25)';
+    ctx.beginPath();
+    ctx.moveTo(padding.left, scale.baselineY);
+    ctx.lineTo(padding.left + chartW, scale.baselineY);
+    ctx.stroke();
+  }
+}

package/src/components/data/chart/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Supported Canvas chart types.
+ */
+export type ChartType = 'bar' | 'line' | 'pie' | 'doughnut';
+
+/**
+ * Single dataset to render on a chart.
+ */
+export interface ChartDataset {
+  /** Dataset label displayed in the legend and accessibility attributes. */
+  label: string;
+
+  /**
+   * Numerical values for the dataset.
+   * `null` or `undefined` indicates a missing data point.
+   */
+  data: (number | null | undefined)[];
+
+  /**
+   * Background color for bars, slices, or area fill.
+   * Accepts any valid CSS color string or an array of colors.
+   */
+  backgroundColor?: string | string[];
+
+  /**
+   * Border color for lines or bars.
+   * Accepts any valid CSS color string or an array of colors.
+   */
+  borderColor?: string | string[];
+
+  /**
+   * Border / line width in pixels.
+   * @defaultValue 2
+   */
+  borderWidth?: number;
+
+  /**
+   * Whether the dataset is initially hidden.
+   * @defaultValue false
+   */
+  hidden?: boolean;
+}
+
+/**
+ * Chart input data structure.
+ */
+export interface ChartData {
+  /** Category labels for the X axis or slice labels for pie/doughnut. */
+  labels: string[];
+
+  /** Array of datasets to render. */
+  datasets: ChartDataset[];
+}
+
+/**
+ * Chart rendering, grid, scale, and accessibility options.
+ */
+export interface ChartOptions {
+  /**
+   * Legend position configuration.
+   * @defaultValue { position: 'bottom' }
+   */
+  legend?: {
+    position?: 'top' | 'bottom' | 'none';
+  };
+
+  /**
+   * Backward compatible plugin configuration.
+   */
+  plugins?: {
+    legend?: {
+      position?: 'top' | 'bottom' | 'none';
+    };
+  };
+
+  /**
+   * Whether to render horizontal grid lines.
+   * @defaultValue true
+   */
+  showGrid?: boolean;
+
+  /**
+   * Whether to show axis labels.
+   * @defaultValue true
+   */
+  showLabels?: boolean;
+
+  /**
+   * Forced value for the Y axis scale.
+   */
+  min?: number;
+  max?: number;
+
+  /**
+   * Accessible description for screen readers.
+   */
+  ariaLabel?: string;
+}

package/src/components/data/chart/validator.ts

@@ -0,0 +1,98 @@
+import type { ChartData, ChartDataset } from './types';
+
+export interface ChartValidationResult {
+  valid: boolean;
+  data?: ChartData;
+  error?: string;
+}
+
+/**
+ * Validates chart data structure (especially useful for NUI game events).
+ */
+export function validateChartData(raw: unknown): ChartValidationResult {
+  if (!raw || typeof raw !== 'object') {
+    return { valid: false, error: 'Chart data must be an object' };
+  }
+
+  const obj = raw as Record<string, unknown>;
+  if (!Array.isArray(obj.datasets)) {
+    return { valid: false, error: 'Missing datasets array' };
+  }
+
+  const labels = Array.isArray(obj.labels)
+    ? obj.labels.map((l) => (l !== null && l !== undefined ? String(l) : ''))
+    : [];
+
+  const datasets: ChartDataset[] = [];
+  for (let i = 0; i < obj.datasets.length; i++) {
+    const ds = obj.datasets[i];
+    if (!ds || typeof ds !== 'object') {
+      return { valid: false, error: `Dataset at index ${i} is not a valid object` };
+    }
+
+    const dsObj = ds as Record<string, unknown>;
+    const label = typeof dsObj.label === 'string' ? dsObj.label : `Dataset ${i + 1}`;
+
+    if (!Array.isArray(dsObj.data)) {
+      return { valid: false, error: `Dataset '${label}' is missing data array` };
+    }
+
+    const data: (number | null | undefined)[] = [];
+    for (let j = 0; j < dsObj.data.length; j++) {
+      const v = dsObj.data[j];
+      if (v === null || v === undefined) {
+        data.push(null);
+      } else if (typeof v === 'number' && Number.isFinite(v)) {
+        data.push(v);
+      } else {
+        return {
+          valid: false,
+          error: `Dataset '${label}' contains invalid value at index ${j}: ${String(v)} (expected finite number or null)`,
+        };
+      }
+    }
+
+    let borderWidth: number | undefined = undefined;
+    if (dsObj.borderWidth !== undefined) {
+      if (typeof dsObj.borderWidth !== 'number' || !Number.isFinite(dsObj.borderWidth) || dsObj.borderWidth < 0) {
+        return { valid: false, error: `Dataset '${label}' has invalid borderWidth (must be number >= 0)` };
+      }
+      borderWidth = dsObj.borderWidth;
+    }
+
+    let backgroundColor: string | string[] | undefined = undefined;
+    if (typeof dsObj.backgroundColor === 'string') {
+      backgroundColor = dsObj.backgroundColor;
+    } else if (Array.isArray(dsObj.backgroundColor)) {
+      if (dsObj.backgroundColor.some((c) => typeof c !== 'string' || !c.trim())) {
+        return { valid: false, error: `Dataset '${label}' has invalid colors in backgroundColor` };
+      }
+      backgroundColor = dsObj.backgroundColor as string[];
+    }
+
+    let borderColor: string | string[] | undefined = undefined;
+    if (typeof dsObj.borderColor === 'string') {
+      borderColor = dsObj.borderColor;
+    } else if (Array.isArray(dsObj.borderColor)) {
+      if (dsObj.borderColor.some((c) => typeof c !== 'string' || !c.trim())) {
+        return { valid: false, error: `Dataset '${label}' has invalid colors in borderColor` };
+      }
+      borderColor = dsObj.borderColor as string[];
+    }
+
+    datasets.push({
+      label,
+      data,
+      backgroundColor,
+      borderColor,
+      borderWidth,
+      hidden: typeof dsObj.hidden === 'boolean' ? dsObj.hidden : false,
+    });
+  }
+
+  if (datasets.length === 0) {
+    return { valid: false, error: 'datasets array cannot be empty' };
+  }
+
+  return { valid: true, data: { labels, datasets } };
+}