@object-ui/plugin-report 4.0.12 → 4.2.1

package/dist/packages/plugin-report/src/buildChartData.d.ts

@@ -0,0 +1,38 @@
+import { ReportRow } from './hooks/useReportData';
+import { SpecReport, SpecReportColumn } from '../../types/src';
+export interface ChartAdapterLabelResolvers {
+    /** Resolve a friendly label for a measure column. Used for the chart's y-axis legend. */
+    resolveColumnLabel?: (col: SpecReportColumn) => string | undefined;
+    /** Resolve a friendly label for an implicit `count` measure given the yAxis field. */
+    resolveCountLabel?: (yField: string) => string | undefined;
+    /** Resolve a friendly display label for an x-axis bucket value (e.g. translate picklist values). */
+    resolveAxisValue?: (field: string, rawValue: unknown) => string | undefined;
+}
+export interface ChartAdapterInput {
+    report: SpecReport;
+    rows: ReportRow[];
+    labels?: ChartAdapterLabelResolvers;
+}
+export interface ChartAdapterOutput {
+    /** `{ data, xAxisKey, series, chartType }` ready for `<SchemaRenderer type="chart">`. */
+    schema: ChartSchema | null;
+    /** Human-readable diagnostic when we can't build a chart (missing xAxis, etc.). */
+    diagnostic?: string;
+}
+type ChartType = 'bar' | 'column' | 'horizontal-bar' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'radar' | 'scatter';
+export interface ChartSchema {
+    type: 'chart';
+    chartType: ChartType;
+    data: Array<Record<string, unknown>>;
+    xAxisKey: string;
+    series: Array<{
+        dataKey: string;
+        label?: string;
+    }>;
+    title?: string;
+    showLegend?: boolean;
+    showDataLabels?: boolean;
+    className?: string;
+}
+export declare function buildChartData({ report, rows, labels }: ChartAdapterInput): ChartAdapterOutput;
+export {};

package/dist/packages/plugin-report/src/drill.d.ts

@@ -0,0 +1,63 @@
+import { ActionDef, ActionHandler, ActionRunner } from '../../core/src';
+import { SpecReport } from '../../types/src';
+/** Open-target for a drill. */
+export type DrillOpenIn = 'current' | 'modal' | 'new-tab';
+/** Drill target — either a list filtered down to the group, or a specific record. */
+export type DrillView = 'list' | 'detail' | (string & {});
+/** Serializable shape of a `type: 'drill'` action. */
+export interface DrillActionDef extends ActionDef {
+    type: 'drill';
+    objectName: string;
+    filter?: Record<string, unknown>;
+    view?: DrillView;
+    recordId?: string | number;
+    openIn?: DrillOpenIn;
+}
+/** Resolved navigation target produced by a drill handler. */
+export interface DrillNavigateTarget {
+    objectName: string;
+    filter?: Record<string, unknown>;
+    view?: DrillView;
+    recordId?: string | number;
+    openIn?: DrillOpenIn;
+}
+/** Options passed when creating a drill handler. */
+export interface DrillHandlerOptions {
+    /**
+     * Host-supplied navigation callback. The handler invokes this with a
+     * fully-resolved target so the host can decide whether to push to
+     * router, open a modal, or open a new tab.
+     */
+    navigate: (target: DrillNavigateTarget) => void | Promise<void>;
+}
+/**
+ * Compose a `drill` action from a spec report + group key.
+ *
+ * Filter precedence (later overrides earlier where keys conflict):
+ *   1. `report.filter` (definition-time)
+ *   2. `runtimeFilter` (URL / user selection)
+ *   3. `groupKey` (the row/cell the user actually clicked)
+ *
+ * All three are combined via `$and` so backend filter engines see the
+ * full intersection.
+ */
+export declare function buildDrillAction(report: SpecReport, groupKey: Record<string, unknown>, options?: {
+    runtimeFilter?: Record<string, unknown>;
+    view?: DrillView;
+    recordId?: string | number;
+    openIn?: DrillOpenIn;
+}): DrillActionDef;
+/** Type guard for drill actions. */
+export declare function isDrillAction(action: ActionDef | undefined | null): action is DrillActionDef;
+/**
+ * Build an `ActionHandler` for the `drill` action type.
+ *
+ * Register it on an `ActionRunner` (or `ActionEngine`'s runner) via
+ * `runner.registerHandler('drill', createDrillHandler({ navigate }))`.
+ */
+export declare function createDrillHandler(opts: DrillHandlerOptions): ActionHandler;
+/**
+ * Register the drill handler on an `ActionRunner` instance. Returns an
+ * unregister function for cleanup (useful in React effects).
+ */
+export declare function registerDrillHandler(runner: ActionRunner, opts: DrillHandlerOptions): () => void;

package/dist/packages/plugin-report/src/hooks/useReportData.d.ts

@@ -0,0 +1,131 @@
+import { SpecReport, SpecReportColumn, SpecReportGrouping, SpecReportDateGranularity } from '../../../types/src';
+export interface ReportRow {
+    /** Group key path, e.g. `{ region: 'East', quarter: '2024-Q1' }`. Empty `{}` for the grand-total row. */
+    groupKey: Record<string, unknown>;
+    /** Display labels for the key path, in `[down..., across...]` order. */
+    groupPath: string[];
+    /** Aggregated values, keyed as `${field}__${aggregate}` (or just `${field}` for passthrough columns). */
+    values: Record<string, unknown>;
+    /** Number of underlying raw rows in this group. */
+    count: number;
+    /** Child rows for nested groupings. Undefined at the leaf level. */
+    children?: ReportRow[];
+}
+export interface UseReportDataResult {
+    rows: ReportRow[];
+    rawRows: Record<string, unknown>[];
+    totals: Record<string, unknown>;
+    /** Pivoted matrix shape — populated when `report.groupingsAcross` is non-empty. */
+    pivot: PivotMatrix | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    drillDown: (groupKey: Record<string, unknown>) => Record<string, unknown>[];
+}
+/**
+ * 2D pivot output. `rowHeaders` × `colHeaders` form the matrix; `cells[rowId][colId]`
+ * holds the per-cell aggregated values keyed by `columnKey()`. Totals are
+ * pre-computed so the renderer doesn't need to re-aggregate.
+ */
+export interface PivotHeader {
+    /** Group key path, e.g. `{ region: 'EMEA' }` (row) or `{ closeQuarter: '2024-Q1' }` (col). */
+    key: Record<string, unknown>;
+    /** Display labels in nesting order. */
+    path: string[];
+    /** Stable id derived from `path` — use as React key + lookup key into `cells`. */
+    id: string;
+}
+export interface PivotMatrix {
+    rowHeaders: PivotHeader[];
+    colHeaders: PivotHeader[];
+    /** `cells[rowId][colId] = { 'amount__sum': 1200, ... }`. Missing cells are absent (renderer fills with 0/—). */
+    cells: Record<string, Record<string, Record<string, unknown>>>;
+    /** Row totals across all columns, keyed by `rowId`. */
+    rowTotals: Record<string, Record<string, unknown>>;
+    /** Column totals across all rows, keyed by `colId`. */
+    colTotals: Record<string, Record<string, unknown>>;
+    /** Grand total across the entire matrix. */
+    grandTotal: Record<string, unknown>;
+    columns: readonly SpecReportColumn[];
+    downGroupings: readonly SpecReportGrouping[];
+    acrossGroupings: readonly SpecReportGrouping[];
+}
+export interface UseReportDataOptions {
+    /**
+     * Adapter exposing `find(resource, params)` and optionally `aggregate(resource, query)`.
+     * - When `.aggregate` is present, the hook prefers it for reports with date
+     *   bucketing or pure aggregations — the server then runs DATE_TRUNC + GROUP
+     *   BY natively and returns one row per bucket.
+     * - When only `.find` is present, the hook falls back to raw rows + client
+     *   bucketing (see `bucketDate` / `groupingValue`).
+     * If the hook stays idle, no fetch happens.
+     */
+    dataSource?: {
+        find?: (resource: string, params?: Record<string, unknown>) => Promise<unknown>;
+        aggregate?: (resource: string, query: Record<string, unknown>) => Promise<unknown>;
+    };
+    /** Filter merged on top of `report.filter` via `$and` (e.g., URL params, user selections). */
+    runtimeFilter?: Record<string, unknown>;
+    /** Optional `$top` cap for the raw fetch. Defaults to 5000. */
+    maxRows?: number;
+    /** When `false`, skips fetching. Defaults to `true`. */
+    enabled?: boolean;
+    /** Pre-fetched rows. When provided, bypasses `dataSource` entirely. */
+    rows?: Record<string, unknown>[];
+    /**
+     * When true (default), prefer `dataSource.aggregate()` for reports that
+     * carry date granularity or any aggregating column. Set false to force the
+     * client-side path (useful for tests / debugging).
+     */
+    preferServerAggregation?: boolean;
+}
+/** Stable key for a column's aggregated output: `field__aggregate` (or just `field`). */
+export declare function columnKey(col: SpecReportColumn): string;
+/** Format a Date into a string bucket according to a date granularity. */
+export declare function bucketDate(value: unknown, granularity: SpecReportDateGranularity): string | null;
+/** Extract the group value for a single grouping, applying dateGranularity if set. */
+export declare function groupingValue(row: Record<string, unknown>, grouping: SpecReportGrouping): string;
+/**
+ * Compute aggregates for an array of rows against a list of columns.
+ * `unique` returns the count of distinct non-null values; `count` includes nulls.
+ */
+export declare function aggregateRows(rows: Record<string, unknown>[], columns: readonly SpecReportColumn[]): Record<string, unknown>;
+/**
+ * Recursive grouping. Each grouping level produces a nested `ReportRow[]`.
+ * The final leaf level still aggregates over the bucket so callers always have
+ * `values` available without re-walking children.
+ */
+export declare function groupAndAggregate(rows: Record<string, unknown>[], groupings: readonly SpecReportGrouping[], columns: readonly SpecReportColumn[], parentKey?: Record<string, unknown>, parentPath?: string[]): ReportRow[];
+/**
+ * Build a 2D pivot matrix from raw rows. Rows are bucketed by every
+ * `downGroupings` field path; columns by every `acrossGroupings` field path.
+ * Each cell is then aggregated independently with the report's columns.
+ *
+ * - When either dimension is empty, the matrix degenerates: a single header
+ *   with empty path is emitted so the renderer can still display a 1×N or
+ *   N×1 strip without special-casing.
+ * - Header ordering honours each grouping's `sort` ('asc' default, 'desc' opt-in).
+ * - `limit` on the *head* grouping of each dimension is respected (matches
+ *   `groupAndAggregate`); deeper limits are ignored to preserve totals.
+ */
+export declare function pivotRows(rows: Record<string, unknown>[], columns: readonly SpecReportColumn[], downGroupings: readonly SpecReportGrouping[], acrossGroupings: readonly SpecReportGrouping[]): PivotMatrix;
+/** Combine two FilterCondition objects via `$and`, dropping empty ones. */
+export declare function mergeFilters(a: Record<string, unknown> | undefined, b: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/** Collect all fields referenced by groupings + columns + sort + filter (for $select). */
+export declare function collectFields(report: SpecReport): string[];
+/**
+ * Build a `QueryAST`-style payload for `dataSource.aggregate()`. Groupings
+ * with `dateGranularity` are emitted as structured objects so spec-aware
+ * backends can do server-side DATE_TRUNC; backends that don't recognise the
+ * field gracefully treat them as the bare field name (the engine's
+ * in-memory fallback handles the rest).
+ *
+ * Returns `null` when the report has no groupings *and* no aggregating
+ * columns — in that case there's no work for `aggregate()` to do and the
+ * hook should stick with `find()`.
+ */
+export declare function buildAggregateQuery(report: SpecReport, runtimeFilter: Record<string, unknown> | undefined, maxRows: number): Record<string, unknown> | null;
+/**
+ * Run a spec `Report` and return its rows, totals, and a drill-down helper.
+ */
+export declare function useReportData(report: SpecReport | undefined, options?: UseReportDataOptions): UseReportDataResult;

package/dist/packages/plugin-report/src/index.d.ts

@@ -1,11 +1,24 @@
 import { ReportRenderer } from './ReportRenderer';
+import { LegacyReportRenderer } from './LegacyReportRenderer';
 import { ReportViewer } from './ReportViewer';
 import { ReportBuilder } from './ReportBuilder';
 import { ReportConfigPanel } from './ReportConfigPanel';
-export { ReportRenderer, ReportViewer, ReportBuilder, ReportConfigPanel };
+import { SpecReportGrid } from './SpecReportGrid';
+import { MatrixRenderer } from './MatrixRenderer';
+import { JoinedReportRenderer } from './JoinedReportRenderer';
+export { ReportRenderer, LegacyReportRenderer, ReportViewer, ReportBuilder, ReportConfigPanel, SpecReportGrid, MatrixRenderer, JoinedReportRenderer };
+export type { ReportRendererProps, ReportRendererSchema } from './ReportRenderer';
+export type { LegacyReportRendererProps } from './LegacyReportRenderer';
+export type { SpecReportGridProps } from './SpecReportGrid';
+export type { MatrixRendererProps, MatrixCellClickArgs } from './MatrixRenderer';
+export type { JoinedReportRendererProps } from './JoinedReportRenderer';
+export { buildDrillAction, createDrillHandler, registerDrillHandler, isDrillAction, } from './drill';
+export type { DrillActionDef, DrillHandlerOptions, DrillNavigateTarget, DrillOpenIn, DrillView, } from './drill';
 export type { AvailableField } from './ReportConfigPanel';
 export { formatValue } from './formatValue';
 export { exportReport, exportAsCSV, exportAsJSON, exportAsHTML, exportAsPDF, exportAsExcel } from './ReportExportEngine';
 export { ScheduleConfig } from './ScheduleConfig';
 export { exportWithLiveData, exportExcelWithFormulas, createScheduleTrigger, } from './LiveReportExporter';
 export type { LiveExportOptions, LiveExportResult, ExcelColumnConfig, ScheduleTriggerCallback, } from './LiveReportExporter';
+export { useReportData, columnKey, bucketDate, groupingValue, aggregateRows, groupAndAggregate, pivotRows, buildAggregateQuery, mergeFilters, collectFields, } from './hooks/useReportData';
+export type { ReportRow, PivotHeader, PivotMatrix, UseReportDataResult, UseReportDataOptions, } from './hooks/useReportData';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/plugin-report",
-  "version": "4.0.12",
+  "version": "4.2.1",
   "type": "module",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
@@ -21,12 +21,15 @@
   "dependencies": {
     "clsx": "^2.1.1",
     "lucide-react": "^1.16.0",
+    "react-i18next": "^17.0.7",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "4.0.12",
-    "@object-ui/core": "4.0.12",
-    "@object-ui/fields": "4.0.12",
-    "@object-ui/react": "4.0.12",
-    "@object-ui/types": "4.0.12"
+    "@object-ui/components": "4.2.1",
+    "@object-ui/core": "4.2.1",
+    "@object-ui/fields": "4.2.1",
+    "@object-ui/i18n": "4.2.1",
+    "@object-ui/plugin-grid": "4.2.1",
+    "@object-ui/react": "4.2.1",
+    "@object-ui/types": "4.2.1"
   },
   "peerDependencies": {
     "react": "^18.0.0",