@quicdata/analytics 0.0.3 → 0.0.5

package/widgets/analytics-widget.js

@@ -0,0 +1,230 @@
+import { __decorate } from "tslib";
+import { LitElement, html, css, nothing } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { fetchWidgetDefinition } from '../core/fetch-data.js';
+// Register inner widgets so they are defined when we render them
+import './bar-chart.js';
+import './line-chart.js';
+import './pie-chart.js';
+import './table.js';
+/** Map API chart_type to inner widget type. */
+const CHART_TYPE_TO_TAG = {
+    Bar: 'analytics-bar-chart',
+    BarHorizontal: 'analytics-bar-chart',
+    Line: 'analytics-line-chart',
+    Pie: 'analytics-pie-chart',
+    Donut: 'analytics-pie-chart',
+    Number: 'analytics-table', // KPI: fallback to table for now
+    Table: 'analytics-table',
+};
+/**
+ * Generic analytics widget: pass widgetId + apiUrl (and optional config);
+ * fetches the widget definition and renders the appropriate chart/table internally.
+ * Use this so developers don't need to know the chart type.
+ */
+let AnalyticsWidget = class AnalyticsWidget extends LitElement {
+    static { this.styles = css `
+    :host {
+      display: block;
+      width: 100%;
+      height: 100%;
+      min-height: 120px;
+    }
+    .widget-inner {
+      width: 100%;
+      height: 100%;
+      min-height: 120px;
+    }
+    .loading,
+    .error {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 120px;
+      padding: 1rem;
+      color: #6b7280;
+    }
+    .error {
+      color: #b91c1c;
+    }
+    .loading-spinner {
+      width: 2rem;
+      height: 2rem;
+      border: 2px solid #e5e7eb;
+      border-top-color: #3b82f6;
+      border-radius: 50%;
+      animation: analytics-widget-spin 0.7s linear infinite;
+    }
+    @keyframes analytics-widget-spin {
+      to { transform: rotate(360deg); }
+    }
+  `; }
+    constructor() {
+        super();
+        this.widgetId = '';
+        this.apiUrl = '';
+        this.title = '';
+        this.dataParams = {};
+        this.dashboard = null;
+        this.lazy = false;
+        this.prefetchMargin = '200px';
+        this._chartType = '';
+        this._definition = null;
+        this._loading = false;
+        this._error = null;
+    }
+    updated(changed) {
+        if (!this.apiUrl || !this.widgetId || this._loading)
+            return;
+        if (changed.has('widgetId') || changed.has('apiUrl')) {
+            this._chartType = '';
+            this._definition = null;
+            this._loadDefinition();
+        }
+        else if (!this._chartType) {
+            this._loadDefinition();
+        }
+    }
+    async _loadDefinition() {
+        if (!this.apiUrl || !this.widgetId || this._loading)
+            return;
+        this._loading = true;
+        this._error = null;
+        try {
+            const def = await fetchWidgetDefinition(this.apiUrl, this.widgetId);
+            this._chartType = def.chart_type;
+            this._definition = {
+                title: def.title,
+                filters: def.filters,
+                hide_filter: def.hide_filter,
+            };
+        }
+        catch (e) {
+            this._error = e instanceof Error ? e.message : String(e);
+            this._chartType = '';
+            this._definition = null;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    get _innerTag() {
+        if (!this._chartType)
+            return '';
+        return CHART_TYPE_TO_TAG[this._chartType] ?? 'analytics-table';
+    }
+    _renderInnerWidget() {
+        const common = {
+            widgetId: this.widgetId,
+            apiUrl: this.apiUrl,
+            title: this.title,
+            dataParams: this.dataParams ?? {},
+            dashboard: this.dashboard,
+            lazy: this.lazy,
+            prefetchMargin: this.prefetchMargin || '200px',
+            initialDefinition: this._definition ?? undefined,
+        };
+        const tag = this._innerTag;
+        switch (tag) {
+            case 'analytics-bar-chart':
+                return html `<analytics-bar-chart
+          widget-id=${common.widgetId}
+          api-url=${common.apiUrl}
+          .title=${common.title}
+          .dataParams=${common.dataParams}
+          .dashboard=${common.dashboard}
+          .initialDefinition=${common.initialDefinition}
+          ?lazy=${common.lazy}
+          prefetch-margin=${common.prefetchMargin}
+        ></analytics-bar-chart>`;
+            case 'analytics-line-chart':
+                return html `<analytics-line-chart
+          widget-id=${common.widgetId}
+          api-url=${common.apiUrl}
+          .title=${common.title}
+          .dataParams=${common.dataParams}
+          .dashboard=${common.dashboard}
+          .initialDefinition=${common.initialDefinition}
+          ?lazy=${common.lazy}
+          prefetch-margin=${common.prefetchMargin}
+        ></analytics-line-chart>`;
+            case 'analytics-pie-chart':
+                return html `<analytics-pie-chart
+          widget-id=${common.widgetId}
+          api-url=${common.apiUrl}
+          .title=${common.title}
+          .dataParams=${common.dataParams}
+          .dashboard=${common.dashboard}
+          .initialDefinition=${common.initialDefinition}
+          ?lazy=${common.lazy}
+          prefetch-margin=${common.prefetchMargin}
+        ></analytics-pie-chart>`;
+            case 'analytics-table':
+                return html `<analytics-table
+          widget-id=${common.widgetId}
+          api-url=${common.apiUrl}
+          .title=${common.title}
+          .dataParams=${common.dataParams}
+          .dashboard=${common.dashboard}
+          .initialDefinition=${common.initialDefinition}
+          ?lazy=${common.lazy}
+          prefetch-margin=${common.prefetchMargin}
+        ></analytics-table>`;
+            default:
+                return nothing;
+        }
+    }
+    render() {
+        if (this._loading) {
+            return html `
+        <div class="loading" aria-busy="true" aria-live="polite">
+          <div class="loading-spinner" aria-hidden="true"></div>
+        </div>
+      `;
+        }
+        if (this._error) {
+            return html `<div class="error" role="alert">${this._error}</div>`;
+        }
+        if (!this._innerTag) {
+            return nothing;
+        }
+        return html `<div class="widget-inner">${this._renderInnerWidget()}</div>`;
+    }
+};
+__decorate([
+    property({ type: String, attribute: 'widget-id' })
+], AnalyticsWidget.prototype, "widgetId", void 0);
+__decorate([
+    property({ type: String, attribute: 'api-url' })
+], AnalyticsWidget.prototype, "apiUrl", void 0);
+__decorate([
+    property({ type: String })
+], AnalyticsWidget.prototype, "title", void 0);
+__decorate([
+    property({ type: Object })
+], AnalyticsWidget.prototype, "dataParams", void 0);
+__decorate([
+    property({ type: Object })
+], AnalyticsWidget.prototype, "dashboard", void 0);
+__decorate([
+    property({ type: Boolean })
+], AnalyticsWidget.prototype, "lazy", void 0);
+__decorate([
+    property({ type: String, attribute: 'prefetch-margin' })
+], AnalyticsWidget.prototype, "prefetchMargin", void 0);
+__decorate([
+    state()
+], AnalyticsWidget.prototype, "_chartType", void 0);
+__decorate([
+    state()
+], AnalyticsWidget.prototype, "_definition", void 0);
+__decorate([
+    state()
+], AnalyticsWidget.prototype, "_loading", void 0);
+__decorate([
+    state()
+], AnalyticsWidget.prototype, "_error", void 0);
+AnalyticsWidget = __decorate([
+    customElement('analytics-widget')
+], AnalyticsWidget);
+export { AnalyticsWidget };

package/widgets/bar-chart.d.ts

@@ -0,0 +1,13 @@
+import type { EChartsOption } from 'echarts/types/dist/option';
+import { BaseChartWidget } from './base-chart.js';
+/**
+ * Bar chart widget (Apache ECharts). Use data-url or inline data.
+ * When widgetData is present (from API), use its categories + series so x-axis is correct (e.g. split_by).
+ * Otherwise first column = categories, remaining = series.
+ */
+export declare class BarChartWidget extends BaseChartWidget {
+    buildOption(data: Record<string, unknown>[], meta: Record<string, {
+        type?: string;
+    }>, widgetData?: unknown): EChartsOption;
+}
+//# sourceMappingURL=bar-chart.d.ts.map

package/widgets/bar-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar-chart.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/widgets/bar-chart.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAuBlD;;;;GAIG;AACH,qBACa,cAAe,SAAQ,eAAe;IACxC,WAAW,CAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EACvC,UAAU,CAAC,EAAE,OAAO,GACnB,aAAa;CAsDjB"}

package/widgets/bar-chart.js

@@ -0,0 +1,77 @@
+import { __decorate } from "tslib";
+import { customElement } from 'lit/decorators.js';
+import { BaseChartWidget } from './base-chart.js';
+const LEGEND_NAME_MAX_LEN = 25;
+function legendConfig(multipleSeries) {
+    if (!multipleSeries)
+        return undefined;
+    return {
+        type: 'scroll',
+        bottom: 8,
+        left: 'center',
+        formatter: (name) => name.length > LEGEND_NAME_MAX_LEN ? name.slice(0, LEGEND_NAME_MAX_LEN) + '…' : name,
+    };
+}
+/**
+ * Bar chart widget (Apache ECharts). Use data-url or inline data.
+ * When widgetData is present (from API), use its categories + series so x-axis is correct (e.g. split_by).
+ * Otherwise first column = categories, remaining = series.
+ */
+let BarChartWidget = class BarChartWidget extends BaseChartWidget {
+    buildOption(data, meta, widgetData) {
+        const wd = widgetData;
+        // Prefer widgetData whenever API sent it (categories = x-axis, series = one per split) so x-axis is never wrong.
+        if (wd && typeof wd === 'object' && Array.isArray(wd.categories)) {
+            const categories = wd.categories.map(String);
+            const seriesList = Array.isArray(wd.series) ? wd.series : [];
+            const series = seriesList.map((s) => ({
+                name: String(s?.name ?? ''),
+                type: 'bar',
+                data: Array.isArray(s?.data) ? s.data.map((v) => Number(v) || 0) : [],
+                stack: wd.stack ? 'total' : undefined,
+            }));
+            const multiSeries = series.length > 1;
+            const isHorizontal = wd.chartType === 'BarHorizontal';
+            return {
+                grid: {
+                    left: isHorizontal ? 120 : 48,
+                    right: 24,
+                    top: 24,
+                    bottom: multiSeries ? 80 : 48,
+                },
+                tooltip: { trigger: 'axis' },
+                legend: legendConfig(multiSeries),
+                xAxis: isHorizontal ? { type: 'value' } : { type: 'category', data: categories },
+                yAxis: isHorizontal ? { type: 'category', data: categories } : { type: 'value' },
+                series,
+            };
+        }
+        const keys = data.length ? Object.keys(data[0]) : Object.keys(meta);
+        if (keys.length === 0) {
+            return { xAxis: { type: 'category', data: [] }, yAxis: { type: 'value' }, series: [] };
+        }
+        const categoryKey = keys[0];
+        const valueKeys = keys.slice(1).filter((k) => meta[k]?.type === 'number' || typeof (data[0]?.[k]) === 'number');
+        const categories = [...new Set(data.map((r) => String(r[categoryKey] ?? '')))];
+        const series = valueKeys.length
+            ? valueKeys.map((name) => ({
+                name,
+                type: 'bar',
+                data: data.map((r) => Number(r[name]) || 0),
+            }))
+            : [{ name: categoryKey, type: 'bar', data: data.map((r) => Number(r[categoryKey]) || 0) }];
+        const multiSeries = series.length > 1;
+        return {
+            grid: { left: 48, right: 24, top: 24, bottom: multiSeries ? 80 : 48 },
+            tooltip: { trigger: 'axis' },
+            legend: legendConfig(multiSeries),
+            xAxis: { type: 'category', data: categories },
+            yAxis: { type: 'value' },
+            series,
+        };
+    }
+};
+BarChartWidget = __decorate([
+    customElement('analytics-bar-chart')
+], BarChartWidget);
+export { BarChartWidget };

package/widgets/base-chart.d.ts

@@ -0,0 +1,92 @@
+import { LitElement } from 'lit';
+import type { EChartsOption } from 'echarts/types/dist/option';
+import type { WidgetDefinitionSubset } from '../core/fetch-data.js';
+import type { DashboardContainer } from '../dashboard/dashboard-container.js';
+import '../filters/index.js';
+/**
+ * Base Lit + ECharts widget. Fetches data from data-url (Laravel analytics API)
+ * or uses inline data, then renders Apache ECharts.
+ * When dashboard is set, merges dashboard params with dataParams and listens for
+ * analytics-dashboard-filter-change and analytics-dashboard-refresh.
+ */
+export declare abstract class BaseChartWidget extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Optional title override. When unset, the widget uses the title from the API definition. */
+    title: string;
+    /** API URL to fetch data (e.g. /api/analytics/widgets/1/data). When widgetId + apiUrl are set, this is overridden by buildWidgetDataUrl(apiUrl, widgetId). */
+    dataUrl: string;
+    /** Widget id (used with apiUrl to build data URL: /widgets/{id}/data). */
+    widgetId: string;
+    /** API base URL (host + prefix, e.g. /api/analytics). Used with widgetId to build data URL. */
+    apiUrl: string;
+    /** Query params for data-url (e.g. date_from, date_to). Widget params override dashboard params for same key. */
+    dataParams: Record<string, string | number | boolean>;
+    /** When set, widget receives dashboard filter/refresh events and merges dashboard params into requests. */
+    dashboard: DashboardContainer | null;
+    /** Inline data instead of fetching (for designer preview). */
+    data: Record<string, unknown>[] | null;
+    /** Inline meta (columns) when using inline data. */
+    meta: {
+        columns: Record<string, {
+            type?: string;
+        }>;
+    };
+    /** ECharts option overrides merged on top of buildOption() result. */
+    options: Partial<EChartsOption>;
+    /** When true, only fetch/render when widget enters viewport; pause refresh when out of viewport. */
+    lazy: boolean;
+    /** CSS margin around viewport to trigger visibility earlier (e.g. '200px'). Used when lazy is true. */
+    prefetchMargin: string;
+    /** When set (e.g. by analytics-widget), definition is not fetched again; used to avoid duplicate definition requests. */
+    initialDefinition: WidgetDefinitionSubset | undefined;
+    private _loading;
+    private _error;
+    private _loadGeneration;
+    private _loadDataScheduled;
+    private _ignoreNextFilterChange;
+    private _dashboardParams;
+    private _widgetFilters;
+    private _widgetFilterParams;
+    private _hideFilter;
+    private _widgetData;
+    private _chart;
+    private _dashboardEl;
+    private _resizeObserver;
+    /** Single debounce: each resize cancels previous, then we wait and call chart.resize() once. */
+    private _resizeTimeoutId;
+    /** Delay (ms) after last resize event before calling chart.resize(). */
+    private static readonly _RESIZE_DELAY_MS;
+    private _viewportVisible;
+    /** Title from widget definition (API). Optional `title` attribute overrides this. */
+    private _definitionTitle;
+    private _hasLoadedOnce;
+    private _viewportUnobserve;
+    constructor();
+    private _boundOnDashboardFilterChange;
+    private _boundOnDashboardRefresh;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changed: Map<string, unknown>): void;
+    private _attachDashboard;
+    private _detachDashboard;
+    firstUpdated(): void;
+    private _getEffectiveDataUrl;
+    /** Display title: optional host `title` overrides definition title from API. */
+    private get _effectiveTitle();
+    /** Run a callback after the current update cycle to avoid Lit "change-in-update" warning. */
+    private _defer;
+    private _getEffectiveParams;
+    private _loadData;
+    private _renderChart;
+    /**
+     * Build ECharts option from API data. Override in subclasses (bar, line, pie).
+     * When widgetData has categories + series (e.g. from split_by), use those for bar/line.
+     * Default: generic grid + empty series.
+     */
+    buildOption(_data: Record<string, unknown>[], _meta: Record<string, {
+        type?: string;
+    }>, _widgetData?: unknown): EChartsOption;
+    private _onWidgetFilterChange;
+    render(): import("lit-html").TemplateResult<1>;
+}
+//# sourceMappingURL=base-chart.d.ts.map

package/widgets/base-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-chart.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/widgets/base-chart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,MAAM,KAAK,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,KAAK,EAA0B,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAO5F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAM9E,OAAO,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,8BAAsB,eAAgB,SAAQ,UAAU;IACtD,OAAgB,MAAM,0BAuFpB;IAEF,8FAA8F;IAC1D,KAAK,EAAE,MAAM,CAAC;IAElD,8JAA8J;IACnG,OAAO,EAAE,MAAM,CAAC;IAE3E,0EAA0E;IACd,QAAQ,EAAE,MAAM,CAAC;IAE7E,+FAA+F;IACrC,MAAM,EAAE,MAAM,CAAC;IAEzE,iHAAiH;IAC7E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAE1F,2GAA2G;IACvE,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAEzE,8DAA8D;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC;IAE3E,oDAAoD;IAChB,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IAEzF,sEAAsE;IAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAEpE,oGAAoG;IAC/D,IAAI,EAAE,OAAO,CAAC;IAEnD,uGAAuG;IACrC,cAAc,EAAE,MAAM,CAAC;IAEzF,yHAAyH;IACrF,iBAAiB,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAE1F,QAAyB,QAAQ,CAAU;IAC3C,QAAyB,MAAM,CAAgB;IAC/C,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,uBAAuB,CAAS;IACxC,QAAyB,gBAAgB,CAA4C;IACrF,QAAyB,cAAc,CAAqB;IAC5D,QAAyB,mBAAmB,CAA4C;IACxF,QAAyB,WAAW,CAAU;IAC9C,QAAyB,WAAW,CAAU;IAC9C,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,eAAe,CAA+B;IACtD,gGAAgG;IAChG,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAO;IAC/C,QAAyB,gBAAgB,CAAU;IACnD,qFAAqF;IACrF,QAAyB,gBAAgB,CAAS;IAClD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAA6B;;IA0BvD,OAAO,CAAC,6BAA6B,CAInC;IACF,OAAO,CAAC,wBAAwB,CAG9B;IAEO,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAc5B,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA0CrD,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,gBAAgB;IASf,YAAY,IAAI,IAAI;IAoC7B,OAAO,CAAC,oBAAoB;IAO5B,gFAAgF;IAChF,OAAO,KAAK,eAAe,GAE1B;IAED,6FAA6F;IAC7F,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,mBAAmB;YA2Bb,SAAS;IAiFvB,OAAO,CAAC,YAAY;IAuBpB;;;;OAIG;IACH,WAAW,CACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EACxC,WAAW,CAAC,EAAE,OAAO,GACpB,aAAa;IAShB,OAAO,CAAC,qBAAqB;IAIpB,MAAM;CAiChB"}