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

package/src/components/data/chart/NuiChart.svelte

@@ -0,0 +1,384 @@
+<!--
+  @component NuiChart
+  Canvas chart component (bar, line, pie, doughnut) for FiveM NUI.
+-->
+<script module lang="ts">
+  export type {
+    ChartData,
+    ChartDataset,
+    ChartOptions,
+    ChartType,
+  } from "./types";
+</script>
+
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { nui } from "@fivem-nui/svelte";
+  import type { SvelteNuiClient } from "@fivem-nui/svelte";
+  import type {
+    ChartData,
+    ChartDataset,
+    ChartOptions,
+    ChartType,
+  } from "./types";
+  import { getColor } from "./color";
+  import { validateChartData } from "./validator";
+  import { renderChart } from "./registry";
+
+  /**
+   * Props for {@link NuiChart} component.
+   */
+  interface Props {
+    /**
+     * Chart type determining the rendering strategy.
+     * Supported built-in types: `'bar'`, `'line'`, `'pie'`, `'doughnut'` or custom types.
+     */
+    type: ChartType;
+
+    /**
+     * Source chart data passed from parent.
+     */
+    data: ChartData;
+
+    /**
+     * Container width in pixels or CSS units.
+     * @defaultValue '100%'
+     */
+    width?: number | string;
+
+    /**
+     * Canvas height in pixels or CSS units.
+     * @defaultValue '300px'
+     */
+    height?: number | string;
+
+    /**
+     * Optional configuration for grid, Y-scale, legend position, and accessibility.
+     * @defaultValue {}
+     */
+    options?: ChartOptions;
+
+    /**
+     * Optional NUI event name (from game / C#).
+     * When provided, automatically listens for chart updates from NUI.
+     */
+    eventName?: string;
+
+    /**
+     * SvelteNuiClient instance to listen for game events.
+     * @defaultValue singleton `nui` from `@fivem-nui/svelte`
+     */
+    client?: SvelteNuiClient;
+  }
+
+  let {
+    type,
+    data,
+    width = "100%",
+    height = "300px",
+    options = {},
+    eventName,
+    client = nui,
+  }: Props = $props();
+
+  let canvasEl = $state<HTMLCanvasElement | null>(null);
+  let containerEl = $state<HTMLDivElement | null>(null);
+  let rafId: number | null = null;
+
+  // Data sources: separation of parent props, NUI events, and local visibility state
+  let remoteData = $state<ChartData | null>(null);
+  let hiddenIndices = $state<Record<number, boolean>>({});
+  let lastPropsData: ChartData | null = null;
+
+  // New parent props reset remote overrides and local hidden states
+  $effect(() => {
+    if (data !== lastPropsData) {
+      lastPropsData = data;
+      remoteData = null;
+      hiddenIndices = {};
+    }
+  });
+
+  // Listen for NUI updates with runtime validation
+  $effect(() => {
+    if (!eventName || !client) return;
+    const unsub = client.on(eventName, (payload: unknown) => {
+      const validation = validateChartData(payload);
+      if (validation.valid && validation.data) {
+        remoteData = validation.data;
+        hiddenIndices = {};
+      } else {
+        console.warn(
+          `[NuiChart] Rejected invalid payload from event '${eventName}':`,
+          validation.error,
+          payload,
+        );
+      }
+    });
+    return () => unsub();
+  });
+
+  // Effective data combining remote overrides and local visibility toggles
+  const activeRawData = $derived(remoteData ?? data);
+  const currentData = $derived<ChartData>({
+    labels: activeRawData?.labels ?? [],
+    datasets: (activeRawData?.datasets ?? []).map((ds, idx) => ({
+      ...ds,
+      hidden: hiddenIndices[idx] ?? ds.hidden ?? false,
+    })),
+  });
+
+  // Common pie dataset used in renderer and legend
+  const activePieDataset = $derived(
+    currentData.datasets.find((d) => !d.hidden) ?? currentData.datasets[0],
+  );
+
+  /**
+   * Schedules a render on the next animation frame.
+   */
+  function scheduleRender() {
+    if (typeof window === "undefined") return;
+    if (rafId !== null) cancelAnimationFrame(rafId);
+    rafId = requestAnimationFrame(() => {
+      rafId = null;
+      if (!canvasEl) return;
+      const rect = canvasEl.getBoundingClientRect();
+      const w = rect.width || (typeof width === "number" ? width : 400);
+      const h = rect.height || (typeof height === "number" ? height : 300);
+      renderChart(canvasEl, w, h, type, currentData, options);
+    });
+  }
+
+  $effect(() => {
+    void type;
+    void currentData;
+    void options;
+    void width;
+    void height;
+    scheduleRender();
+  });
+
+  onMount(() => {
+    scheduleRender();
+
+    if (containerEl && typeof ResizeObserver !== "undefined") {
+      const ro = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          if (entry.contentRect.width > 0 && entry.contentRect.height > 0) {
+            scheduleRender();
+          }
+        }
+      });
+      ro.observe(containerEl);
+      return () => {
+        ro.disconnect();
+        if (rafId !== null) cancelAnimationFrame(rafId);
+      };
+    }
+
+    return () => {
+      if (rafId !== null) cancelAnimationFrame(rafId);
+    };
+  });
+
+  const legendPos = $derived(
+    options.legend?.position ?? options.plugins?.legend?.position ?? "bottom",
+  );
+  const showLegend = $derived(legendPos !== "none");
+
+  /** Accessible description for screen readers. */
+  const resolvedAriaLabel = $derived.by(() => {
+    if (options.ariaLabel) return options.ariaLabel;
+    const labels = currentData.labels || [];
+    const labelsSummary =
+      labels.length > 5
+        ? `${labels.slice(0, 5).join(", ")} and ${labels.length - 5} more`
+        : labels.join(", ");
+    return `Chart of type ${type}.${labels.length ? ` Categories: ${labelsSummary}` : ""}`;
+  });
+
+  /**
+   * Toggles dataset visibility locally without mutating source data.
+   */
+  function toggleDataset(index: number) {
+    const isCurrentlyHidden = currentData.datasets[index]?.hidden ?? false;
+    hiddenIndices[index] = !isCurrentlyHidden;
+  }
+</script>
+
+<div
+  class="nui-chart-container"
+  bind:this={containerEl}
+  style="width: {typeof width === 'number' ? `${width}px` : width};"
+>
+  {#if showLegend && legendPos === "top"}
+    <div class="nui-chart__legend nui-chart__legend--top">
+      {#if type === "pie" || type === "doughnut"}
+        {#if activePieDataset && !activePieDataset.hidden}
+          {#each currentData.labels || [] as label, idx}
+            {#if (activePieDataset.data[idx] ?? 0) > 0}
+              <div class="nui-chart__legend-item">
+                <span
+                  class="nui-chart__legend-color"
+                  style="background-color: {getColor(
+                    activePieDataset.backgroundColor,
+                    idx,
+                  )}"
+                ></span>
+                <span class="nui-chart__legend-label">{label}</span>
+              </div>
+            {/if}
+          {/each}
+        {/if}
+      {:else}
+        {#each currentData.datasets as ds, idx}
+          <button
+            type="button"
+            class="nui-chart__legend-btn"
+            class:nui-chart__legend-btn--hidden={ds.hidden}
+            aria-pressed={!ds.hidden}
+            aria-label="{ds.hidden ? 'Show' : 'Hide'} series: {ds.label}"
+            onclick={() => toggleDataset(idx)}
+          >
+            <span
+              class="nui-chart__legend-color"
+              style="background-color: {getColor(
+                ds.borderColor || ds.backgroundColor,
+                idx,
+              )}"
+            ></span>
+            <span class="nui-chart__legend-label">{ds.label}</span>
+          </button>
+        {/each}
+      {/if}
+    </div>
+  {/if}
+
+  <canvas
+    bind:this={canvasEl}
+    class="nui-chart"
+    role="img"
+    aria-label={resolvedAriaLabel}
+    style="width: 100%; height: {typeof height === 'number'
+      ? `${height}px`
+      : height};"
+  >
+    <p>{resolvedAriaLabel}</p>
+  </canvas>
+
+  {#if showLegend && legendPos !== "top"}
+    <div class="nui-chart__legend nui-chart__legend--bottom">
+      {#if type === "pie" || type === "doughnut"}
+        {#if activePieDataset && !activePieDataset.hidden}
+          {#each currentData.labels || [] as label, idx}
+            {#if (activePieDataset.data[idx] ?? 0) > 0}
+              <div class="nui-chart__legend-item">
+                <span
+                  class="nui-chart__legend-color"
+                  style="background-color: {getColor(
+                    activePieDataset.backgroundColor,
+                    idx,
+                  )}"
+                ></span>
+                <span class="nui-chart__legend-label">{label}</span>
+              </div>
+            {/if}
+          {/each}
+        {/if}
+      {:else}
+        {#each currentData.datasets as ds, idx}
+          <button
+            type="button"
+            class="nui-chart__legend-btn"
+            class:nui-chart__legend-btn--hidden={ds.hidden}
+            aria-pressed={!ds.hidden}
+            aria-label="{ds.hidden ? 'Show' : 'Hide'} series: {ds.label}"
+            onclick={() => toggleDataset(idx)}
+          >
+            <span
+              class="nui-chart__legend-color"
+              style="background-color: {getColor(
+                ds.borderColor || ds.backgroundColor,
+                idx,
+              )}"
+            ></span>
+            <span class="nui-chart__legend-label">{ds.label}</span>
+          </button>
+        {/each}
+      {/if}
+    </div>
+  {/if}
+</div>
+
+<style>
+  .nui-chart-container {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    font-family: inherit;
+    box-sizing: border-box;
+  }
+
+  .nui-chart {
+    display: block;
+    border-radius: var(--nui-radius, 0.375rem);
+    box-sizing: border-box;
+  }
+
+  .nui-chart__legend {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: 1rem;
+    padding: 0.25rem 0;
+  }
+
+  .nui-chart__legend-item,
+  .nui-chart__legend-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    font-size: 0.75rem;
+    color: var(--nui-muted, #a1a1aa);
+    line-height: 1;
+  }
+
+  .nui-chart__legend-btn {
+    background: transparent;
+    border: none;
+    padding: 0.125rem 0.25rem;
+    border-radius: 0.25rem;
+    cursor: pointer;
+    font: inherit;
+    transition:
+      opacity 0.15s ease,
+      text-decoration 0.15s ease;
+  }
+
+  .nui-chart__legend-btn:hover {
+    opacity: 0.8;
+  }
+
+  .nui-chart__legend-btn:focus-visible {
+    outline: 2px solid var(--nui-primary, #6366f1);
+    outline-offset: 2px;
+  }
+
+  .nui-chart__legend-btn--hidden {
+    opacity: 0.4;
+    text-decoration: line-through;
+  }
+
+  .nui-chart__legend-color {
+    width: 0.75rem;
+    height: 0.75rem;
+    border-radius: 0.125rem;
+    flex-shrink: 0;
+  }
+
+  .nui-chart__legend-label {
+    line-height: 1;
+  }
+</style>

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

@@ -0,0 +1,83 @@
+export const DEFAULT_COLORS = [
+  '#6366f1', // indigo
+  '#06b6d4', // cyan
+  '#10b981', // emerald
+  '#f59e0b', // amber
+  '#ef4444', // red
+  '#8b5cf6', // purple
+  '#ec4899', // pink
+];
+
+let helperCtx: CanvasRenderingContext2D | null = null;
+
+function getHelperCtx(): CanvasRenderingContext2D | null {
+  if (typeof document === 'undefined') return null;
+  if (!helperCtx) {
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    helperCtx = canvas.getContext('2d', { willReadFrequently: true });
+  }
+  return helperCtx;
+}
+
+/**
+ * Returns valid color string from dataset property or fallback palette.
+ */
+export function getColor(item: string | string[] | undefined, index: number): string {
+  const safeIdx = Number.isFinite(index) ? Math.floor(Math.abs(index)) : 0;
+  if (Array.isArray(item) && item.length > 0) {
+    const color = item[safeIdx % item.length];
+    if (typeof color === 'string' && color.trim()) {
+      return color.trim();
+    }
+  }
+  if (typeof item === 'string' && item.trim()) {
+    return item.trim();
+  }
+  return DEFAULT_COLORS[safeIdx % DEFAULT_COLORS.length];
+}
+
+/**
+ * Converts color (hex, rgb, hsl, named) to rgba(r, g, b, alpha).
+ */
+export function colorToRgba(color: string, alpha: number): string {
+  const a = Math.max(0, Math.min(1, Number.isFinite(alpha) ? alpha : 1));
+  if (!color || typeof color !== 'string') return `rgba(99, 102, 241, ${a})`;
+  const trimmed = color.trim();
+
+  // Fast path for hex formats: #RGB or #RRGGBB
+  if (/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(trimmed)) {
+    let hex = trimmed.slice(1);
+    if (hex.length === 3) {
+      hex = hex.split('').map((c) => c + c).join('');
+    }
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${a})`;
+  }
+
+  // Fast path for rgb(...) or rgba(...)
+  const rgbMatch = trimmed.match(/^rgba?\(\s*(\d{1,3})\s*[, ]\s*(\d{1,3})\s*[, ]\s*(\d{1,3})/i);
+  if (rgbMatch) {
+    return `rgba(${rgbMatch[1]}, ${rgbMatch[2]}, ${rgbMatch[3]}, ${a})`;
+  }
+
+  // Canvas parser for named colors, hsl, etc.
+  const ctx = getHelperCtx();
+  if (ctx) {
+    try {
+      ctx.clearRect(0, 0, 1, 1);
+      ctx.fillStyle = '#000000';
+      ctx.fillStyle = trimmed;
+      ctx.fillRect(0, 0, 1, 1);
+      const pixel = ctx.getImageData(0, 0, 1, 1).data;
+      return `rgba(${pixel[0]}, ${pixel[1]}, ${pixel[2]}, ${a})`;
+    } catch {
+      // Fallback on environment error
+    }
+  }
+
+  return `rgba(99, 102, 241, ${a})`;
+}

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

@@ -0,0 +1,10 @@
+export { default as NuiChart } from './NuiChart.svelte';
+export * from './types';
+export * from './color';
+export * from './validator';
+export * from './scale';
+export * from './registry';
+export * from './renderers/base';
+export * from './renderers/bar';
+export * from './renderers/line';
+export * from './renderers/pie';

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

@@ -0,0 +1,71 @@
+import type { ChartData, ChartOptions, ChartType } from './types';
+import type { ChartRenderer, RenderContext } from './renderers/base';
+import { drawMessage } from './renderers/base';
+import { BarChartRenderer } from './renderers/bar';
+import { LineChartRenderer } from './renderers/line';
+import { PieChartRenderer } from './renderers/pie';
+
+const renderers: Map<string, ChartRenderer> = new Map<string, ChartRenderer>([
+  ['bar', new BarChartRenderer()],
+  ['line', new LineChartRenderer()],
+  ['pie', new PieChartRenderer(false)],
+  ['doughnut', new PieChartRenderer(true)],
+]);
+
+/**
+ * Registers or overrides a chart renderer.
+ */
+export function registerChartRenderer(type: string, renderer: ChartRenderer): void {
+  renderers.set(type, renderer);
+}
+
+/**
+ * Returns the registered renderer for given chart type.
+ */
+export function getChartRenderer(type: ChartType | string): ChartRenderer | undefined {
+  return renderers.get(type);
+}
+
+/**
+ * Renders chart on the given canvas element with hidpi scaling.
+ */
+export function renderChart(
+  canvasEl: HTMLCanvasElement,
+  w: number,
+  h: number,
+  type: ChartType | string,
+  currentData: ChartData | undefined,
+  options: ChartOptions = {}
+): void {
+  const ctx = canvasEl.getContext('2d');
+  if (!ctx) return;
+
+  const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+  canvasEl.width = Math.floor(w * dpr);
+  canvasEl.height = Math.floor(h * dpr);
+
+  ctx.resetTransform?.();
+  ctx.scale(dpr, dpr);
+  ctx.clearRect(0, 0, w, h);
+
+  if (!currentData || !currentData.datasets || currentData.datasets.length === 0) {
+    drawMessage(ctx, w, h, 'No data to display');
+    return;
+  }
+
+  const renderer = getChartRenderer(type);
+  if (!renderer) {
+    drawMessage(ctx, w, h, `Unsupported chart type: ${type}`);
+    return;
+  }
+
+  const context: RenderContext = {
+    canvas: canvasEl,
+    ctx,
+    width: w,
+    height: h,
+    dpr,
+  };
+
+  renderer.render(context, currentData, options);
+}

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

@@ -0,0 +1,90 @@
+import type { ChartData, ChartOptions } from '../types';
+import type { ChartRenderer, RenderContext } from './base';
+import { drawMessage } from './base';
+import { getColor } from '../color';
+import { calculateScale, drawGridAndYLabels, DEFAULT_CHART_PADDING } from '../scale';
+
+/**
+ * Renderer for bar and column charts.
+ */
+export class BarChartRenderer 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 groupCount = Math.max(labels.length, ...datasets.map((d) => d.data.length), 1);
+    const groupW = chartW / groupCount;
+    const totalBarWidth = (groupW * 0.7) / datasets.length;
+    const barGap = Math.min(4, totalBarWidth * 0.2);
+
+    for (let g = 0; g < groupCount; g++) {
+      const groupX = padding.left + g * groupW;
+
+      if (showLabels && labels[g]) {
+        ctx.fillStyle = '#a1a1aa';
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'top';
+        ctx.fillText(labels[g], groupX + groupW / 2, padding.top + chartH + 8);
+      }
+
+      datasets.forEach((ds, dsIndex) => {
+        const val = ds.data[g];
+        if (val === null || val === undefined || !Number.isFinite(val)) {
+          return;
+        }
+
+        const clampedVal = Math.max(scale.minVal, Math.min(scale.maxVal, val));
+        const valY = padding.top + chartH - ((clampedVal - scale.minVal) / scale.range) * chartH;
+        const barX = groupX + (groupW - totalBarWidth * datasets.length) / 2 + dsIndex * totalBarWidth;
+
+        let barY: number;
+        let barH: number;
+        if (clampedVal >= 0) {
+          barY = valY;
+          barH = scale.baselineY - valY;
+        } else {
+          barY = scale.baselineY;
+          barH = valY - scale.baselineY;
+        }
+
+        if (barH <= 0) return;
+
+        const barWidth = Math.max(1, totalBarWidth - barGap);
+        ctx.fillStyle = getColor(ds.backgroundColor, dsIndex);
+
+        const r = Math.min(4, barH / 2, barWidth / 2);
+        ctx.beginPath();
+        if (clampedVal >= 0) {
+          ctx.moveTo(barX, scale.baselineY);
+          ctx.lineTo(barX, barY + r);
+          ctx.quadraticCurveTo(barX, barY, barX + r, barY);
+          ctx.lineTo(barX + barWidth - r, barY);
+          ctx.quadraticCurveTo(barX + barWidth, barY, barX + barWidth, barY + r);
+          ctx.lineTo(barX + barWidth, scale.baselineY);
+        } else {
+          ctx.moveTo(barX, scale.baselineY);
+          ctx.lineTo(barX, barY + barH - r);
+          ctx.quadraticCurveTo(barX, barY + barH, barX + r, barY + barH);
+          ctx.lineTo(barX + barWidth - r, barY + barH);
+          ctx.quadraticCurveTo(barX + barWidth, barY + barH, barX + barWidth, barY + barH - r);
+          ctx.lineTo(barX + barWidth, scale.baselineY);
+        }
+        ctx.closePath();
+        ctx.fill();
+      });
+    }
+  }
+}

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

@@ -0,0 +1,32 @@
+import type { ChartData, ChartOptions } from '../types';
+
+export interface RenderContext {
+  canvas: HTMLCanvasElement;
+  ctx: CanvasRenderingContext2D;
+  width: number;
+  height: number;
+  dpr: number;
+}
+
+/**
+ * Canvas chart renderer interface.
+ */
+export interface ChartRenderer {
+  render(context: RenderContext, data: ChartData, options: ChartOptions): void;
+}
+
+/**
+ * Draws centered text message on the canvas (eg. empty state).
+ */
+export function drawMessage(
+  ctx: CanvasRenderingContext2D,
+  width: number,
+  height: number,
+  text: string
+): void {
+  ctx.fillStyle = '#71717a';
+  ctx.font = '13px sans-serif';
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.fillText(text, width / 2, height / 2);
+}