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

package/dist/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/dist/components/data/chart/NuiChart.svelte.d.ts

@@ -0,0 +1,49 @@
+export type { ChartData, ChartDataset, ChartOptions, ChartType, } from "./types";
+import type { SvelteNuiClient } from "@fivem-nui/svelte";
+import type { ChartData, ChartOptions, ChartType } from "./types";
+/**
+ * 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;
+}
+/**
+ * NuiChart
+ * Canvas chart component (bar, line, pie, doughnut) for FiveM NUI.
+ */
+declare const NuiChart: import("svelte").Component<Props, {}, "">;
+type NuiChart = ReturnType<typeof NuiChart>;
+export default NuiChart;

package/dist/components/data/chart/color.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_COLORS: string[];
+/**
+ * Returns valid color string from dataset property or fallback palette.
+ */
+export declare function getColor(item: string | string[] | undefined, index: number): string;
+/**
+ * Converts color (hex, rgb, hsl, named) to rgba(r, g, b, alpha).
+ */
+export declare function colorToRgba(color: string, alpha: number): string;

package/dist/components/data/chart/color.js

@@ -0,0 +1,78 @@
+export const DEFAULT_COLORS = [
+    '#6366f1', // indigo
+    '#06b6d4', // cyan
+    '#10b981', // emerald
+    '#f59e0b', // amber
+    '#ef4444', // red
+    '#8b5cf6', // purple
+    '#ec4899', // pink
+];
+let helperCtx = null;
+function getHelperCtx() {
+    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, index) {
+    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, alpha) {
+    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/dist/components/data/chart/index.d.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/dist/components/data/chart/index.js

@@ -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/dist/components/data/chart/registry.d.ts

@@ -0,0 +1,14 @@
+import type { ChartData, ChartOptions, ChartType } from './types';
+import type { ChartRenderer } from './renderers/base';
+/**
+ * Registers or overrides a chart renderer.
+ */
+export declare function registerChartRenderer(type: string, renderer: ChartRenderer): void;
+/**
+ * Returns the registered renderer for given chart type.
+ */
+export declare function getChartRenderer(type: ChartType | string): ChartRenderer | undefined;
+/**
+ * Renders chart on the given canvas element with hidpi scaling.
+ */
+export declare function renderChart(canvasEl: HTMLCanvasElement, w: number, h: number, type: ChartType | string, currentData: ChartData | undefined, options?: ChartOptions): void;

package/dist/components/data/chart/registry.js

@@ -0,0 +1,53 @@
+import { drawMessage } from './renderers/base';
+import { BarChartRenderer } from './renderers/bar';
+import { LineChartRenderer } from './renderers/line';
+import { PieChartRenderer } from './renderers/pie';
+const renderers = new Map([
+    ['bar', new BarChartRenderer()],
+    ['line', new LineChartRenderer()],
+    ['pie', new PieChartRenderer(false)],
+    ['doughnut', new PieChartRenderer(true)],
+]);
+/**
+ * Registers or overrides a chart renderer.
+ */
+export function registerChartRenderer(type, renderer) {
+    renderers.set(type, renderer);
+}
+/**
+ * Returns the registered renderer for given chart type.
+ */
+export function getChartRenderer(type) {
+    return renderers.get(type);
+}
+/**
+ * Renders chart on the given canvas element with hidpi scaling.
+ */
+export function renderChart(canvasEl, w, h, type, currentData, options = {}) {
+    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 = {
+        canvas: canvasEl,
+        ctx,
+        width: w,
+        height: h,
+        dpr,
+    };
+    renderer.render(context, currentData, options);
+}

package/dist/components/data/chart/renderers/bar.d.ts

@@ -0,0 +1,8 @@
+import type { ChartData, ChartOptions } from '../types';
+import type { ChartRenderer, RenderContext } from './base';
+/**
+ * Renderer for bar and column charts.
+ */
+export declare class BarChartRenderer implements ChartRenderer {
+    render(context: RenderContext, data: ChartData, options: ChartOptions): void;
+}