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

package/dist/components/data/chart/renderers/bar.js

@@ -0,0 +1,79 @@
+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 {
+    render(context, data, options) {
+        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;
+                let barH;
+                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/dist/components/data/chart/renderers/base.d.ts

@@ -0,0 +1,18 @@
+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 declare function drawMessage(ctx: CanvasRenderingContext2D, width: number, height: number, text: string): void;

package/dist/components/data/chart/renderers/base.js

@@ -0,0 +1,10 @@
+/**
+ * Draws centered text message on the canvas (eg. empty state).
+ */
+export function drawMessage(ctx, width, height, text) {
+    ctx.fillStyle = '#71717a';
+    ctx.font = '13px sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(text, width / 2, height / 2);
+}

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

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

package/dist/components/data/chart/renderers/line.js

@@ -0,0 +1,89 @@
+import { drawMessage } from './base';
+import { getColor, colorToRgba } from '../color';
+import { calculateScale, drawGridAndYLabels, DEFAULT_CHART_PADDING } from '../scale';
+/**
+ * Renderer for line charts.
+ */
+export class LineChartRenderer {
+    render(context, data, options) {
+        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 = [];
+            let currentSegment = [];
+            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/dist/components/data/chart/renderers/pie.d.ts

@@ -0,0 +1,10 @@
+import type { ChartData, ChartOptions } from '../types';
+import type { ChartRenderer, RenderContext } from './base';
+/**
+ * Renderer for pie and doughnut charts.
+ */
+export declare class PieChartRenderer implements ChartRenderer {
+    private readonly isDoughnut;
+    constructor(isDoughnut?: boolean);
+    render(context: RenderContext, data: ChartData, _options: ChartOptions): void;
+}

package/dist/components/data/chart/renderers/pie.js

@@ -0,0 +1,55 @@
+import { drawMessage } from './base';
+import { getColor } from '../color';
+/**
+ * Renderer for pie and doughnut charts.
+ */
+export class PieChartRenderer {
+    isDoughnut;
+    constructor(isDoughnut = false) {
+        this.isDoughnut = isDoughnut;
+    }
+    render(context, data, _options) {
+        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/dist/components/data/chart/scale.d.ts

@@ -0,0 +1,22 @@
+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 declare const DEFAULT_CHART_PADDING: ChartPadding;
+/**
+ * Calculates Y axis scale supporting both positive and negative values.
+ */
+export declare function calculateScale(datasets: ChartData['datasets'], options: ChartOptions, chartH: number, paddingTop?: number): ScaleInfo;
+/**
+ * Draws horizontal grid lines, Y axis labels, and highlighted zero baseline.
+ */
+export declare function drawGridAndYLabels(ctx: CanvasRenderingContext2D, padding: ChartPadding, chartW: number, chartH: number, scale: ScaleInfo, options: ChartOptions): void;

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

@@ -0,0 +1,101 @@
+export const DEFAULT_CHART_PADDING = {
+    top: 20,
+    right: 20,
+    bottom: 35,
+    left: 45,
+};
+/**
+ * Calculates Y axis scale supporting both positive and negative values.
+ */
+export function calculateScale(datasets, options, chartH, paddingTop = DEFAULT_CHART_PADDING.top) {
+    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;
+    let maxVal;
+    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, padding, chartW, chartH, scale, options) {
+    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/dist/components/data/chart/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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/dist/components/data/chart/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,10 @@
+import type { ChartData } from './types';
+export interface ChartValidationResult {
+    valid: boolean;
+    data?: ChartData;
+    error?: string;
+}
+/**
+ * Validates chart data structure (especially useful for NUI game events).
+ */
+export declare function validateChartData(raw: unknown): ChartValidationResult;

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

@@ -0,0 +1,82 @@
+/**
+ * Validates chart data structure (especially useful for NUI game events).
+ */
+export function validateChartData(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return { valid: false, error: 'Chart data must be an object' };
+    }
+    const obj = raw;
+    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 = [];
+    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;
+        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 = [];
+        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 = 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 = 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;
+        }
+        let borderColor = 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;
+        }
+        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 } };
+}