@quicdata/analytics 0.0.3 → 0.0.4

package/core/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Analytics API auth: Bearer token for all requests (reports, widgets, datasets).
+ * Set once via setAnalyticsApiKey(); every fetch in this package will include it.
+ */
+/**
+ * Set the API key (Bearer token) for all subsequent analytics API requests.
+ * Pass null or '' to clear. Used by report, chart widget, and table widget requests.
+ */
+export declare function setAnalyticsApiKey(key: string | null): void;
+/**
+ * Get the current API key (for tests or inspection). Prefer setAnalyticsApiKey for configuration.
+ */
+export declare function getAnalyticsApiKey(): string | null;
+/**
+ * Request init options for fetch: credentials and optional Authorization header.
+ * Use in all analytics fetch() calls so Bearer token is applied when set.
+ */
+export declare function getAnalyticsRequestInit(init?: RequestInit): RequestInit;
+//# sourceMappingURL=auth.d.ts.map

package/core/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/core/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAWvE"}

package/core/auth.js

@@ -0,0 +1,34 @@
+/**
+ * Analytics API auth: Bearer token for all requests (reports, widgets, datasets).
+ * Set once via setAnalyticsApiKey(); every fetch in this package will include it.
+ */
+let apiKey = null;
+/**
+ * Set the API key (Bearer token) for all subsequent analytics API requests.
+ * Pass null or '' to clear. Used by report, chart widget, and table widget requests.
+ */
+export function setAnalyticsApiKey(key) {
+    apiKey = key && String(key).trim() ? String(key).trim() : null;
+}
+/**
+ * Get the current API key (for tests or inspection). Prefer setAnalyticsApiKey for configuration.
+ */
+export function getAnalyticsApiKey() {
+    return apiKey;
+}
+/**
+ * Request init options for fetch: credentials and optional Authorization header.
+ * Use in all analytics fetch() calls so Bearer token is applied when set.
+ */
+export function getAnalyticsRequestInit(init) {
+    const base = {
+        credentials: 'same-origin',
+        ...init,
+    };
+    if (apiKey) {
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${apiKey}`);
+        return { ...base, headers };
+    }
+    return base;
+}

package/core/fetch-data.d.ts

@@ -0,0 +1,115 @@
+import type { AnalyticsDataResponse, FilterDefinition } from './types.js';
+/** Build widget data URL from API base (host + prefix) and widget id. Path: /widgets/{id}/data */
+export declare function buildWidgetDataUrl(apiUrl: string, widgetId: string | number): string;
+/** Build widget definition URL. Path: /widgets/{id} (no data). */
+export declare function buildWidgetDefinitionUrl(apiUrl: string, widgetId: string | number): string;
+/** Build report definition URL. GET /reports/definitions/{id} */
+export declare function buildReportDefinitionUrl(apiUrl: string, reportId: string | number): string;
+/** Build report filters URL (with optional query params for context). GET /reports/definitions/{id}/filters */
+export declare function buildReportFiltersUrl(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): string;
+/** Build report data URL (JSON, same shape as widget/data). GET /reports/definitions/{id}/data */
+export declare function buildReportDataUrl(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): string;
+/** Build report preview URL (HTML). GET /reports/definitions/{id}/preview */
+export declare function buildReportPreviewUrl(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): string;
+/** Build report PDF download URL. GET /reports/definitions/{id}/pdf */
+export declare function buildReportPdfUrl(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): string;
+/** Build report Excel download URL. GET /reports/definitions/{id}/excel */
+export declare function buildReportExcelUrl(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): string;
+/** Append query params to a base URL (e.g. from definition preview_url). */
+export declare function appendParamsToUrl(baseUrl: string, params?: Record<string, string | number | boolean>): string;
+/** Report definition API response (GET /reports/definitions/{id}). */
+export interface ReportDefinitionApiResponse {
+    id?: number;
+    name?: string;
+    definition?: Record<string, unknown>;
+    /** Resolved filters (with options for presets); use when present instead of definition.filters. */
+    resolved_filters?: FilterDefinition[];
+    /** URLs from definition model (preview, PDF, Excel). Use these when present. */
+    preview_url?: string;
+    download_pdf_url?: string;
+    download_excel_url?: string;
+    data?: {
+        id?: number;
+        name?: string;
+        definition?: Record<string, unknown>;
+        resolved_filters?: FilterDefinition[];
+        preview_url?: string;
+        download_pdf_url?: string;
+        download_excel_url?: string;
+    };
+}
+/** Result of fetchReportDefinition: name, filters, and optional export URLs from definition. */
+export interface ReportDefinitionResult {
+    name: string;
+    /** Filter definitions from definition.filters (same shape as FilterDefinition). */
+    filters: FilterDefinition[];
+    /** When present, use for toolbar links (append current params as query). */
+    preview_url?: string;
+    download_pdf_url?: string;
+    download_excel_url?: string;
+}
+/** Fetch report definition (name, filters) from GET /reports/definitions/{id}. No separate filters API call. */
+export declare function fetchReportDefinition(apiUrl: string, reportId: string | number): Promise<ReportDefinitionResult>;
+/** Fetch resolved report filters (with options) from GET /reports/definitions/{id}/filters. */
+export declare function fetchReportFilters(apiUrl: string, reportId: string | number, params?: AnalyticsRequestParams): Promise<{
+    filters: FilterDefinition[];
+}>;
+/** Chart type from API: Bar, BarHorizontal, Line, Pie, Donut, Number, Table. */
+export type WidgetChartType = 'Bar' | 'BarHorizontal' | 'Line' | 'Pie' | 'Donut' | 'Number' | 'Table';
+/** Definition subset passed from analytics-widget to inner chart/table to avoid refetching. */
+export interface WidgetDefinitionSubset {
+    title: string;
+    filters: FilterDefinition[];
+    hide_filter: boolean;
+}
+/** Widget definition response (GET /widgets/{id}): definition.title, definition.chart_type, definition.filters, etc. */
+export interface WidgetDefinitionApiResponse {
+    definition?: {
+        title?: string;
+        chart_type?: string;
+        filters?: FilterDefinition[];
+        hide_filter?: boolean;
+        refresh_rate?: number;
+    };
+    /** Top-level name when response is not wrapped in data (e.g. from some backends). */
+    name?: string;
+}
+/**
+ * Fetch widget definition (no data) from Laravel GET /widgets/{id}. Use first so filters (and default_value) are available before fetching data.
+ */
+export declare function fetchWidgetDefinition(apiUrl: string, widgetId: string | number): Promise<{
+    title: string;
+    chart_type: WidgetChartType;
+    filters: FilterDefinition[];
+    hide_filter: boolean;
+    refresh_rate: number;
+}>;
+/** Params for analytics request. dashboard_params is sent as nested query keys (dashboard_params[key]=value). */
+export type AnalyticsRequestParams = Record<string, string | number | boolean | Record<string, string | number | boolean>>;
+/**
+ * Fetch widget/dataset data from Laravel analytics API.
+ * @param dataUrl Full URL (e.g. /api/analytics/widgets/1/data) or path; optional params appended.
+ * @param params Query params merged into URL. Use dashboard_params key for dashboard-level filters (sent as dashboard_params[key]=value).
+ * @returns Parsed { data, meta } from API.
+ */
+export declare function fetchAnalyticsData(dataUrl: string, params?: AnalyticsRequestParams): Promise<AnalyticsDataResponse>;
+/** Full widget/data response shape from Laravel (widgetData, data, meta, filters, refresh_rate, hide_filter). */
+export interface WidgetDataApiResponse {
+    data?: Record<string, unknown>[];
+    meta?: {
+        columns: Record<string, {
+            type?: string;
+        }>;
+    };
+    widgetData?: unknown;
+    filters?: FilterDefinition[];
+    refresh_rate?: number;
+    /** When true, widget filter toolbar is hidden and widget filter params are not sent. */
+    hide_filter?: boolean;
+}
+/**
+ * Fetch widget data from Laravel widget/data endpoint. Returns full response including filters and refresh_rate.
+ * Use for widgets that need filter definitions from the API (e.g. per-widget filter bar).
+ */
+export declare function fetchWidgetData(dataUrl: string, params?: AnalyticsRequestParams): Promise<WidgetDataApiResponse>;
+//# sourceMappingURL=fetch-data.d.ts.map

package/core/fetch-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-data.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/core/fetch-data.ts"],"names":[],"mappings":"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"}

package/core/fetch-data.js

@@ -0,0 +1,210 @@
+import { getAnalyticsRequestInit } from './auth.js';
+/** Build widget data URL from API base (host + prefix) and widget id. Path: /widgets/{id}/data */
+export function buildWidgetDataUrl(apiUrl, widgetId) {
+    const base = (apiUrl || '').replace(/\/$/, '');
+    return `${base}/widgets/${widgetId}/data`;
+}
+/** Build widget definition URL. Path: /widgets/{id} (no data). */
+export function buildWidgetDefinitionUrl(apiUrl, widgetId) {
+    const base = (apiUrl || '').replace(/\/$/, '');
+    return `${base}/widgets/${widgetId}`;
+}
+/** Report definition base path. Path: /reports/definitions/{id} */
+function reportDefinitionBase(apiUrl, reportId) {
+    const base = (apiUrl || '').replace(/\/$/, '');
+    return `${base}/reports/definitions/${reportId}`;
+}
+/** Build report definition URL. GET /reports/definitions/{id} */
+export function buildReportDefinitionUrl(apiUrl, reportId) {
+    return reportDefinitionBase(apiUrl, reportId);
+}
+/** Build report filters URL (with optional query params for context). GET /reports/definitions/{id}/filters */
+export function buildReportFiltersUrl(apiUrl, reportId, params) {
+    const url = new URL(reportDefinitionBase(apiUrl, reportId) + '/filters', typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    return url.toString();
+}
+/** Build report data URL (JSON, same shape as widget/data). GET /reports/definitions/{id}/data */
+export function buildReportDataUrl(apiUrl, reportId, params) {
+    const url = new URL(reportDefinitionBase(apiUrl, reportId) + '/data', typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    return url.toString();
+}
+/** Build report preview URL (HTML). GET /reports/definitions/{id}/preview */
+export function buildReportPreviewUrl(apiUrl, reportId, params) {
+    const url = new URL(reportDefinitionBase(apiUrl, reportId) + '/preview', typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    return url.toString();
+}
+/** Build report PDF download URL. GET /reports/definitions/{id}/pdf */
+export function buildReportPdfUrl(apiUrl, reportId, params) {
+    const url = new URL(reportDefinitionBase(apiUrl, reportId) + '/pdf', typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    return url.toString();
+}
+/** Build report Excel download URL. GET /reports/definitions/{id}/excel */
+export function buildReportExcelUrl(apiUrl, reportId, params) {
+    const url = new URL(reportDefinitionBase(apiUrl, reportId) + '/excel', typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    return url.toString();
+}
+/** Append query params to a base URL (e.g. from definition preview_url). */
+export function appendParamsToUrl(baseUrl, params) {
+    if (!params || Object.keys(params).length === 0)
+        return baseUrl;
+    try {
+        const url = new URL(baseUrl, typeof window !== 'undefined' ? window.location.origin : undefined);
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, String(v)));
+        return url.toString();
+    }
+    catch {
+        const sep = baseUrl.includes('?') ? '&' : '?';
+        const qs = new URLSearchParams(Object.entries(flattenParams(params))).toString();
+        return qs ? `${baseUrl}${sep}${qs}` : baseUrl;
+    }
+}
+/** Fetch report definition (name, filters) from GET /reports/definitions/{id}. No separate filters API call. */
+export async function fetchReportDefinition(apiUrl, reportId) {
+    const url = buildReportDefinitionUrl(apiUrl, reportId);
+    const res = await fetch(url, getAnalyticsRequestInit());
+    if (!res.ok) {
+        throw new Error(`Report definition failed: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    const data = json.data ?? json;
+    const name = (data && typeof data === 'object' && 'name' in data && data.name != null)
+        ? String(data.name)
+        : (json.name != null ? String(json.name) : '');
+    const def = (data && typeof data === 'object' && 'definition' in data && data.definition) ?? json.definition;
+    const rawDef = def && typeof def === 'object' ? def : null;
+    const rawFiltersArr = rawDef && Array.isArray(rawDef.filters) ? rawDef.filters : [];
+    const resolved = (data && typeof data === 'object' && 'resolved_filters' in data && data.resolved_filters)
+        ?? json.resolved_filters;
+    const filters = (Array.isArray(resolved) ? resolved : rawFiltersArr);
+    const previewUrl = (data && typeof data === 'object' && 'preview_url' in data && data.preview_url) ?? json.preview_url;
+    const downloadPdfUrl = (data && typeof data === 'object' && 'download_pdf_url' in data && data.download_pdf_url) ?? json.download_pdf_url;
+    const downloadExcelUrl = (data && typeof data === 'object' && 'download_excel_url' in data && data.download_excel_url) ?? json.download_excel_url;
+    return {
+        name,
+        filters,
+        ...(typeof previewUrl === 'string' && previewUrl && { preview_url: previewUrl }),
+        ...(typeof downloadPdfUrl === 'string' && downloadPdfUrl && { download_pdf_url: downloadPdfUrl }),
+        ...(typeof downloadExcelUrl === 'string' && downloadExcelUrl && { download_excel_url: downloadExcelUrl }),
+    };
+}
+/** Fetch resolved report filters (with options) from GET /reports/definitions/{id}/filters. */
+export async function fetchReportFilters(apiUrl, reportId, params) {
+    const url = buildReportFiltersUrl(apiUrl, reportId, params);
+    const res = await fetch(url, getAnalyticsRequestInit());
+    if (!res.ok) {
+        throw new Error(`Report filters failed: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    return { filters: json.filters ?? [] };
+}
+/**
+ * Fetch widget definition (no data) from Laravel GET /widgets/{id}. Use first so filters (and default_value) are available before fetching data.
+ */
+export async function fetchWidgetDefinition(apiUrl, widgetId) {
+    const url = buildWidgetDefinitionUrl(apiUrl, widgetId);
+    const res = await fetch(url.toString(), getAnalyticsRequestInit());
+    if (!res.ok) {
+        throw new Error(`Widget definition failed: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    const def = json.definition ?? json.data?.definition ?? {};
+    const title = (def.title != null && def.title !== '')
+        ? String(def.title)
+        : (json.data?.name != null ? String(json.data.name) : json.name != null ? String(json.name) : '');
+    const rawChartType = def.chart_type ?? '';
+    const chart_type = ['Bar', 'BarHorizontal', 'Line', 'Pie', 'Donut', 'Number', 'Table'].includes(rawChartType)
+        ? rawChartType
+        : 'Table';
+    return {
+        title: title ?? '',
+        chart_type,
+        filters: def.filters ?? [],
+        hide_filter: def.hide_filter ?? false,
+        refresh_rate: def.refresh_rate ?? 0,
+    };
+}
+function flattenParams(params) {
+    const out = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        if (k === 'dashboard_params' && typeof v === 'object' && v !== null && !Array.isArray(v)) {
+            for (const [dk, dv] of Object.entries(v)) {
+                if (dv !== undefined && dv !== null && dv !== '') {
+                    out[`dashboard_params[${dk}]`] = String(dv);
+                }
+            }
+        }
+        else {
+            out[k] = String(v);
+        }
+    }
+    return out;
+}
+/**
+ * Fetch widget/dataset data from Laravel analytics API.
+ * @param dataUrl Full URL (e.g. /api/analytics/widgets/1/data) or path; optional params appended.
+ * @param params Query params merged into URL. Use dashboard_params key for dashboard-level filters (sent as dashboard_params[key]=value).
+ * @returns Parsed { data, meta } from API.
+ */
+export async function fetchAnalyticsData(dataUrl, params) {
+    const url = new URL(dataUrl, typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    const res = await fetch(url.toString(), getAnalyticsRequestInit());
+    if (!res.ok) {
+        throw new Error(`Analytics data failed: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    return {
+        data: json.data ?? [],
+        meta: json.meta ?? { columns: {} },
+    };
+}
+/**
+ * Fetch widget data from Laravel widget/data endpoint. Returns full response including filters and refresh_rate.
+ * Use for widgets that need filter definitions from the API (e.g. per-widget filter bar).
+ */
+export async function fetchWidgetData(dataUrl, params) {
+    const url = new URL(dataUrl, typeof window !== 'undefined' ? window.location.origin : undefined);
+    if (params) {
+        const flat = flattenParams(params);
+        Object.entries(flat).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    const res = await fetch(url.toString(), getAnalyticsRequestInit());
+    if (!res.ok) {
+        throw new Error(`Widget data failed: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    return {
+        data: json.data ?? [],
+        meta: json.meta ?? { columns: {} },
+        widgetData: json.widgetData,
+        filters: json.filters ?? [],
+        refresh_rate: json.refresh_rate,
+        hide_filter: json.hide_filter ?? false,
+    };
+}

package/core/index.d.ts

@@ -1,2 +1,9 @@
-export declare function core(): string;
+export { setAnalyticsApiKey, getAnalyticsApiKey, getAnalyticsRequestInit } from './auth.js';
+export { buildWidgetDataUrl, buildWidgetDefinitionUrl, fetchAnalyticsData, fetchWidgetData, fetchWidgetDefinition, buildReportDefinitionUrl, buildReportFiltersUrl, buildReportPreviewUrl, buildReportPdfUrl, buildReportExcelUrl, fetchReportDefinition, fetchReportFilters, } from './fetch-data.js';
+export type { AnalyticsRequestParams, WidgetDataApiResponse, WidgetChartType, WidgetDefinitionApiResponse, WidgetDefinitionSubset, ReportDefinitionApiResponse, ReportDefinitionResult, } from './fetch-data.js';
+export type { AnalyticsDataResponse, AnalyticsDataMeta, WidgetDataResponse, WidgetDataOptions, DatetimeGranularity, DimensionRef, MeasureRef, FilterItem, FilterDefinition, FilterOption, CommonChartConfig, BarChartConfig, LineChartConfig, DonutPieChartConfig, NumberKpiChartConfig, TableChartConfig, ChartType, WidgetDefinitionConfig, LazyWidgetOptions, WorkerWidgetOptions, } from './types.js';
+export { observeViewport } from './viewport-observer.js';
+export type { ViewportObserverOptions, ViewportObserverCallbacks } from './viewport-observer.js';
+export { runWidgetTransform } from './widget-transform-runner.js';
+export type { WidgetTransformInput, WidgetTransformOptions } from './widget-transform-runner.js';
 //# sourceMappingURL=index.d.ts.map

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/core/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,IAAI,IAAI,MAAM,CAE7B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/analytics/src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAC5F,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC"}

package/core/index.js

@@ -1,3 +1,4 @@
-export function core() {
-    return 'core';
-}
+export { setAnalyticsApiKey, getAnalyticsApiKey, getAnalyticsRequestInit } from './auth.js';
+export { buildWidgetDataUrl, buildWidgetDefinitionUrl, fetchAnalyticsData, fetchWidgetData, fetchWidgetDefinition, buildReportDefinitionUrl, buildReportFiltersUrl, buildReportPreviewUrl, buildReportPdfUrl, buildReportExcelUrl, fetchReportDefinition, fetchReportFilters, } from './fetch-data.js';
+export { observeViewport } from './viewport-observer.js';
+export { runWidgetTransform } from './widget-transform-runner.js';

package/core/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * API response shape from Laravel analytics dataset/widget data endpoints.
+ * KoolReport returns { data: rows, meta: { columns: Record<string, { type: string }> } }.
+ */
+export interface AnalyticsDataMeta {
+    columns: Record<string, {
+        type?: string;
+    }>;
+}
+export interface AnalyticsDataResponse {
+    data: Record<string, unknown>[];
+    meta: AnalyticsDataMeta;
+}
+/** Full widget/data API response: widgetData, data, meta, filters, refresh_rate. */
+export interface WidgetDataResponse extends AnalyticsDataResponse {
+    widgetData?: unknown;
+    filters?: FilterDefinition[];
+    refresh_rate?: number;
+}
+export interface WidgetDataOptions {
+    /** Base URL for API (e.g. /api/analytics). */
+    baseUrl?: string;
+    /** Query params to append (e.g. date_from, date_to). */
+    params?: Record<string, string | number | boolean>;
+}
+/**
+ * Insights-inspired widget config types.
+ * Emphasis on granularity for datetime dimensions (year, month, quarter, day, week).
+ */
+/** Supported granularity for datetime columns. */
+export type DatetimeGranularity = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour';
+export interface DimensionRef {
+    column_name: string;
+    data_type: string;
+    dimension_name?: string;
+    label?: string;
+    value?: string;
+    /** Only for datetime columns. */
+    granularity?: DatetimeGranularity;
+}
+export interface MeasureRef {
+    aggregation: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    column_name: string;
+    data_type: string;
+    measure_name?: string;
+}
+export interface FilterItem {
+    column?: string;
+    operator?: string;
+    value?: unknown;
+}
+export interface CommonChartConfig {
+    filters?: {
+        filters: FilterItem[];
+        logical_operator: 'And' | 'Or';
+    };
+    limit?: string;
+    order_by?: Array<{
+        column: {
+            column_name: string;
+            type: string;
+        };
+        direction: 'asc' | 'desc';
+    }>;
+}
+export interface BarChartConfig extends CommonChartConfig {
+    x_axis: {
+        dimension: DimensionRef;
+    };
+    y_axis: {
+        series: Array<{
+            measure: MeasureRef;
+        }>;
+        stack?: boolean;
+        overlap?: boolean;
+        normalize?: boolean;
+        show_axis_label?: boolean;
+        show_data_labels?: boolean;
+        show_scrollbar?: boolean;
+    };
+    split_by?: {
+        dimension: DimensionRef;
+        max_split_values?: string;
+    };
+}
+export interface LineChartConfig extends CommonChartConfig {
+    x_axis: {
+        dimension: DimensionRef;
+    };
+    y_axis: {
+        series: Array<{
+            measure: MeasureRef;
+        }>;
+        stack?: boolean;
+        show_axis_label?: boolean;
+        show_data_labels?: boolean;
+    };
+    split_by?: {
+        dimension: DimensionRef;
+        max_split_values?: string;
+    };
+}
+export interface DonutPieChartConfig extends CommonChartConfig {
+    label_column: {
+        dimension: DimensionRef;
+    };
+    value_column: {
+        measure: MeasureRef;
+    };
+    label_position?: 'left' | 'right' | 'top' | 'bottom';
+    legend_position?: 'left' | 'right' | 'top' | 'bottom';
+    max_slices?: string;
+    show_inline_labels?: boolean;
+}
+export interface NumberKpiChartConfig extends CommonChartConfig {
+    number_columns: Array<{
+        measure: MeasureRef;
+    }>;
+    number_column_options?: Array<{
+        decimal?: string;
+        prefix?: string;
+        suffix?: string;
+    }>;
+    date_column?: {
+        dimension: DimensionRef;
+    };
+    comparison?: boolean;
+    shorten_numbers?: boolean;
+    sparkline?: boolean;
+}
+export interface TableChartConfig extends CommonChartConfig {
+    columns?: Array<{
+        column_name: string;
+        label?: string;
+        format?: string;
+        type?: string;
+    }>;
+    page_size?: number;
+}
+export type ChartType = 'Bar' | 'BarHorizontal' | 'Line' | 'Donut' | 'Pie' | 'Number' | 'Table';
+export interface WidgetDefinitionConfig {
+    chart_type: ChartType;
+    config: BarChartConfig | LineChartConfig | DonutPieChartConfig | NumberKpiChartConfig | TableChartConfig;
+}
+/**
+ * Transformed widget data shapes for easier rendering by chart type.
+ * Produced by WidgetDataTransformer from originalData + widget definition.
+ */
+export interface BarWidgetData {
+    chartType: 'Bar' | 'BarHorizontal';
+    categories: string[];
+    series: Array<{
+        name: string;
+        data: number[];
+    }>;
+    stack?: boolean;
+}
+export interface LineWidgetData {
+    chartType: 'Line';
+    categories: string[];
+    series: Array<{
+        name: string;
+        data: number[];
+    }>;
+    stack?: boolean;
+}
+export interface PieWidgetData {
+    chartType: 'Pie' | 'Donut';
+    items: Array<{
+        name: string;
+        value: number;
+    }>;
+}
+export interface NumberKpiWidgetData {
+    chartType: 'Number';
+    values: number[];
+    labels: string[];
+    options?: Array<{
+        decimal?: string;
+        prefix?: string;
+        suffix?: string;
+    }>;
+}
+/** Single header cell: key maps to data column; missing key = presentational only. */
+export interface TableHeaderCell {
+    key?: string;
+    label: string;
+    colspan?: number;
+    rowspan?: number;
+    hide?: boolean;
+}
+/** Column definition from backend (order, visibility, label, align, format, rowspan). */
+export interface TableColumnDef {
+    key: string;
+    label: string;
+    hide?: boolean;
+    align?: string | null;
+    format?: string | null;
+    rowspan?: boolean;
+}
+export interface TableWidgetData {
+    chartType: 'Table';
+    /** Column keys in display order (body cells). */
+    columns: string[];
+    /** Full column definitions (labels, align, format, rowspan, hide). When present, use for headers and styling. */
+    columnDefs?: TableColumnDef[];
+    /** Multi-row header: array of rows, each row array of cells. When present, use instead of single row from columns. */
+    header_rows?: TableHeaderCell[][];
+    /** Body rows. Prefer over raw API `data` when widgetData is from backend. */
+    rows: Record<string, unknown>[];
+    /** Per-column rowspan runs: key -> array of length rows; 0 = merged with above, N = rowspan count. */
+    rowSpanRuns?: Record<string, number[]>;
+    /** Optional font size for table (e.g. '0.75rem', '12px') to adjust for table complexity. */
+    font_size?: string;
+    /** When true, the summary/totals row is sticky (stays visible when scrolling). */
+    totals_sticky?: boolean;
+    /** When totals_sticky is true, 'top' or 'bottom' – where the totals row sticks. */
+    totals_position?: 'top' | 'bottom';
+}
+export type WidgetData = BarWidgetData | LineWidgetData | PieWidgetData | NumberKpiWidgetData | TableWidgetData;
+/** Filter option from API (preset or static options). */
+export interface FilterOption {
+    value: string | number;
+    label?: string;
+}
+/** Filter definition from dashboard or widget API (param_name, type, label, options, default_value). */
+export interface FilterDefinition {
+    param_name: string;
+    type: string;
+    /** UI label (e.g. "Year", "Month"); falls back to param_name if omitted. */
+    label?: string;
+    options?: FilterOption[];
+    /** Default value when none selected; sent as param value if user has not chosen a value. */
+    default_value?: string | number | boolean;
+}
+/** Options for lazy viewport-based rendering of widgets. */
+export interface LazyWidgetOptions {
+    /** 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 as IntersectionObserver rootMargin. */
+    prefetch_margin?: string;
+}
+/** Options for offloading heavy transforms to a Web Worker. */
+export interface WorkerWidgetOptions {
+    /** When true, attempt to run dataset transform (pivot/aggregation) in a worker. Fallback to main thread if unsupported or data small. */
+    use_worker?: boolean;
+    /** Minimum row count to use worker (below this, main thread is used). Default 500. */
+    worker_min_rows?: number;
+}
+//# sourceMappingURL=types.d.ts.map