@acorex-platform/module-report-management-client 0.0.15

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@acorex-platform/module-report-management-client",
+  "version": "0.0.15",
+  "sideEffects": false,
+  "peerDependencies": {
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "module": "fesm2022/acorex-platform-module-report-management-client.mjs",
+  "typings": "types/acorex-platform-module-report-management-client.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/acorex-platform-module-report-management-client.d.ts",
+      "default": "./fesm2022/acorex-platform-module-report-management-client.mjs"
+    },
+    "./contracts": {
+      "types": "./types/acorex-platform-module-report-management-client-contracts.d.ts",
+      "default": "./fesm2022/acorex-platform-module-report-management-client-contracts.mjs"
+    }
+  },
+  "type": "module"
+}

package/types/acorex-platform-module-report-management-client-contracts.d.ts

@@ -0,0 +1,554 @@
+import { AXPWidgetColumnNode } from '@acorex-platform/framework-shared/widget-core';
+import { AXPCommand } from '@acorex-platform/framework-shared/runtime';
+import { AXPQuerySort, AXPEntity } from '@acorex-platform/framework-shared/entity';
+import { AXPFilterClause, AXPActionMenuItem, AXPSystemActionType, AXPCategoryEntity, AXPWidgetNode, AXPExportOptions } from '@acorex-platform/framework-shared/core';
+
+declare const AXPReportManagementFeatureKeys: {
+    readonly ReportBuilder: "ReportManagement:Feature:ReportBuilder";
+    readonly SavedReports: "ReportManagement:Feature:SavedReports";
+    readonly ScheduledReports: "ReportManagement:Feature:ScheduledReports";
+    readonly BackgroundReports: "ReportManagement:Feature:BackgroundReports";
+};
+
+declare const AXPReportManagementMenuKeys: {
+    readonly Root: "report-management:menu";
+    readonly Reports: "report-management:menu:reports";
+    readonly Categories: "report-management:menu:categories";
+    readonly DataSets: "report-management:menu:data-sets";
+};
+
+declare const AXMPermissionsKeys: {
+    ReportManagement: {
+        Management: string;
+        Report: {
+            Management: string;
+            View: string;
+            Create: string;
+            Update: string;
+            Delete: string;
+        };
+        Category: {
+            Management: string;
+            View: string;
+            Create: string;
+            Update: string;
+            Delete: string;
+        };
+    };
+};
+
+declare const RootConfig: {
+    readonly config: {
+        i18n: string;
+        module: string;
+    };
+    readonly module: {
+        readonly route: "report-management";
+        readonly name: string;
+        readonly title: `@${string}:module.title`;
+        readonly icon: "fa-light fa-chart-bar";
+    };
+    readonly entities: {
+        readonly dataSet: {
+            readonly name: "DataSet";
+            readonly title: `t("dataSet", { scope: "${string}" })`;
+            readonly titlePlural: `t("dataSetPlural", { scope: "${string}" })`;
+            readonly icon: "fa-light fa-default";
+        };
+        readonly category: {
+            readonly name: "Category";
+            readonly fullName: `${string}.Category`;
+            readonly title: `@${string}:reports.entities.category.title`;
+            readonly titlePlural: `@${string}:reports.entities.category.plural`;
+            readonly icon: "fa-light fa-folder";
+        };
+        readonly report: {
+            readonly name: "Report";
+            readonly fullName: `${string}.Report`;
+            readonly title: `@${string}:reports.entities.report.title`;
+            readonly titlePlural: `@${string}:reports.entities.report.plural`;
+            readonly icon: "fa-light fa-file-chart-pie";
+        };
+    };
+};
+
+type AXPReportLayoutType = 'table' | 'chart' | 'cards' | 'custom' | 'pdf';
+/**
+ * Report Category - Extends AXPCategoryEntity for consistency and performance
+ *
+ * Inherited properties from AXPCategoryEntity:
+ * - id: string                   - Unique identifier
+ * - title: string                - Display name
+ * - description?: string         - Category description
+ * - parentId?: string            - Parent category ID
+ * - childrenCount: number        - Direct child categories count (enables lazy loading)
+ * - itemsCount?: number          - Direct reports count (replaces hasReport boolean)
+ * - totalChildrenCount?: number - Total nested categories (optional, for analytics)
+ * - totalItemsCount?: number    - Total reports in tree (optional, for analytics)
+ *
+ * Performance benefits:
+ * - Lazy loading support (childrenCount > 0 shows expand icon)
+ * - Report count display (itemsCount shows "5 reports" badge)
+ * - Efficient queries (no need to query to know if expandable)
+ */
+interface AXPReportCategory extends AXPCategoryEntity {
+}
+interface AXPReportDefinition {
+    id: string;
+    title: string;
+    description?: string;
+    categoryIds: string[];
+    parameterGroups: AXPReportParameterGroup[];
+    permissions?: string[];
+    layouts: AXPReportLayoutDefinition[];
+    defaultLayoutId: string;
+}
+type AXPReportLayoutAction = AXPActionMenuItem & {
+    priority: 'primary' | 'secondary';
+};
+/**
+ * Layout Definition - Associates a layout with metadata
+ */
+interface AXPReportLayoutDefinition {
+    id: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    layout: AXPReportLayout;
+    dataSource?: AXPReportDataSource;
+    isDefault?: boolean;
+    actions?: AXPReportLayoutAction[];
+    export?: AXPExportOptions;
+}
+interface AXPReportParameterGroup {
+    name: string;
+    title: string;
+    description?: string;
+    parameters: AXPReportParameter[];
+}
+interface AXPReportParameter {
+    path: string;
+    title: string;
+    description?: string;
+    widget: AXPWidgetNode;
+}
+type AXPReportDataSource = AXPQueryDataSource | AXPCustomDataSource | AXPAggregatedDataSource | AXPTransformedDataSource;
+/**
+ * Query Data Source - Used for executing predefined queries (AXPQuery)
+ */
+interface AXPQueryDataSource {
+    type: 'query';
+    name: string;
+    description?: string;
+    inputs?: AXPReportParameterBinding[];
+    sortFields?: AXPQuerySort[];
+    pagination?: boolean;
+}
+/**
+ * Custom Data Source - Used for fetching data from custom providers like REST APIs or external services
+ */
+interface AXPCustomDataSource {
+    type: 'custom';
+    provider: string;
+    description?: string;
+    inputs?: AXPReportParameterBinding[];
+    options?: {
+        [key: string]: any;
+    };
+}
+/**
+ * Parameter Binding - Maps report-level parameters to actual query/command input structure
+ */
+interface AXPReportParameterBinding {
+    parameterKey: string;
+    bindTo: string;
+}
+/**
+ * Aggregated Data Source - Used for pre-aggregated data optimized for charts
+ */
+interface AXPAggregatedDataSource {
+    type: 'aggregated';
+    baseQuery: string;
+    description?: string;
+    groupBy: string[];
+    aggregations: AXPAggregation[];
+    inputs?: AXPReportParameterBinding[];
+}
+/**
+ * Transformed Data Source - Applies transformations to existing data sources
+ */
+interface AXPTransformedDataSource {
+    type: 'transformed';
+    baseDataSource: AXPReportDataSource;
+    description?: string;
+    transformations: AXPDataTransformation[];
+    inputs?: AXPReportParameterBinding[];
+}
+/**
+ * Aggregation operation for aggregated data sources
+ */
+interface AXPAggregation {
+    field: string;
+    operation: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct';
+    alias?: string;
+}
+/**
+ * Data transformation operation
+ */
+interface AXPDataTransformation {
+    type: 'filter' | 'sort' | 'group' | 'pivot' | 'format';
+    config: Record<string, any>;
+}
+/**
+ * Drill-down target for a grouped report row.
+ * When reportId is omitted, the current report is used.
+ */
+interface AXPReportDrillDownConfig {
+    reportId?: string;
+    layoutId?: string;
+    title?: string;
+    parameters?: Record<string, string>;
+}
+/**
+ * Declares how a summary report is grouped and which detail view opens on drill-down.
+ * Multiple definitions allow alternative drill paths (e.g. by brand vs by category).
+ */
+interface AXPReportGroupByDefinition {
+    fields: string[];
+    displayField?: string;
+    /** When true (default), `displayField` renders as a link instead of a row command column. */
+    linkDisplay?: boolean;
+    title?: string;
+    default?: boolean;
+    priority?: 'primary' | 'secondary';
+    drillDown: AXPReportDrillDownConfig;
+}
+type AXPReportLayout = AXPReportTableLayout | AXPReportChartLayout | AXPReportPdfLayout;
+/**
+ * Table Layout - Displays data in tabular format
+ */
+interface AXPReportTableLayoutRowAction extends AXPActionMenuItem {
+    priority: 'primary' | 'secondary';
+    type: AXPSystemActionType | string;
+    default?: boolean;
+}
+interface AXPReportTableLayout {
+    type: 'table';
+    columns: AXPReportColumn[];
+    actions?: AXPReportTableLayoutRowAction[];
+    options?: AXPTableOptions;
+    groupBy?: AXPReportGroupByDefinition[];
+    conditionalFormatting?: AXPConditionalFormatRule[];
+    summary?: AXPReportSummaryOptions[];
+    header?: AXPReportHeaderFooter;
+    footer?: AXPReportHeaderFooter;
+}
+interface AXPTableOptions {
+    pagination?: boolean;
+    stickyHeader?: boolean;
+    stripedRows?: boolean;
+    sorting?: AXPQuerySort[];
+    selectable?: {
+        mode: 'single' | 'multiple' | 'none';
+    };
+}
+/**
+ * Chart Layout - Displays data in various chart formats
+ */
+interface AXPReportChartLayout {
+    type: 'chart';
+    options: AXPReportChartOptions;
+    header?: AXPReportHeaderFooter;
+    footer?: AXPReportHeaderFooter;
+}
+interface AXPReportChartOptions {
+    chartType: 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'radar' | 'mixed';
+    dataMapping: AXPChartDataMapping;
+    styling?: AXPChartStyling;
+    interactivity?: AXPChartInteractivity;
+}
+/**
+ * Chart Data Mapping Configuration
+ */
+interface AXPChartDataMapping {
+    xField: string;
+    yFields: string | string[];
+    groupBy?: string;
+    seriesField?: string;
+    sizeField?: string;
+    colorField?: string;
+    labelField?: string;
+    aggregation?: {
+        method: 'sum' | 'avg' | 'count' | 'min' | 'max';
+        field: string;
+    };
+}
+/**
+ * Chart Visual Styling Configuration
+ */
+interface AXPChartStyling {
+    colorScheme?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'custom';
+    customColors?: string[];
+    gridLines?: boolean;
+    legend?: {
+        show: boolean;
+        position: 'top' | 'bottom' | 'left' | 'right';
+    };
+    xAxis?: AXPChartAxisConfig;
+    yAxis?: AXPChartAxisConfig;
+    animation?: {
+        enabled: boolean;
+        duration?: number;
+    };
+    chartSpecific?: {
+        bar?: {
+            orientation: 'vertical' | 'horizontal';
+            mode: 'grouped' | 'stacked';
+            barWidth?: number;
+        };
+        line?: {
+            style: 'straight' | 'curved' | 'stepped';
+            showPoints?: boolean;
+            tension?: number;
+        };
+        area?: {
+            mode: 'normal' | 'stacked' | 'percentage';
+            opacity?: number;
+        };
+        pie?: {
+            startAngle?: number;
+            innerRadius?: number;
+            showLabels?: boolean;
+        };
+    };
+}
+/**
+ * Chart Axis Configuration
+ */
+interface AXPChartAxisConfig {
+    title?: string;
+    show?: boolean;
+    type?: 'linear' | 'logarithmic' | 'datetime' | 'category';
+    min?: number | string;
+    max?: number | string;
+    format?: string;
+    gridLines?: boolean;
+    tickInterval?: number;
+}
+/**
+ * Chart Interactivity Configuration
+ */
+interface AXPChartInteractivity {
+    zoom?: {
+        enabled: boolean;
+        mode?: 'x' | 'y' | 'xy';
+    };
+    tooltips?: {
+        enabled: boolean;
+        format?: string;
+        showOnHover?: boolean;
+    };
+    onClick?: {
+        enabled: boolean;
+        action?: 'drill-down' | 'filter' | 'custom';
+    };
+    selection?: {
+        enabled: boolean;
+        mode?: 'single' | 'multiple';
+    };
+    export?: {
+        enabled: boolean;
+        formats?: ('png' | 'jpg' | 'pdf' | 'svg')[];
+    };
+}
+/**
+ * PDF Layout - Displays PDF documents
+ */
+interface AXPReportPdfLayout {
+    type: 'pdf';
+    options?: AXPReportPdfOptions;
+    header?: AXPReportHeaderFooter;
+    footer?: AXPReportHeaderFooter;
+}
+/**
+ * PDF Layout Options
+ */
+interface AXPReportPdfOptions {
+    showDownloadButton?: boolean;
+    showPrintButton?: boolean;
+    showZoomControls?: boolean;
+    showFullscreenButton?: boolean;
+    defaultZoom?: number;
+    height?: string;
+}
+interface AXPReportColumn {
+    field: string;
+    title?: string;
+    visible?: boolean;
+    width?: number | 'auto';
+    align?: 'left' | 'center' | 'right';
+    /** When true, column header supports interactive sort (opt-in). */
+    sortable?: boolean;
+    /** Pin column to the start or end of the table (definition-only). */
+    pin?: 'start' | 'end';
+    widget?: AXPWidgetColumnNode;
+    /**
+     * Optional cell interactivity. When omitted, group-by `displayField` columns
+     * can still render as drill links automatically in report table view.
+     */
+    interactivity?: AXPReportColumnInteractivity;
+}
+/**
+ * Column cell interaction — link triggers a command with the current row as context.
+ * Platform widgets may mirror this via column `options.displayAs: 'link'` in the future.
+ */
+interface AXPReportColumnInteractivity {
+    type: 'link';
+    command: {
+        name: string;
+        options?: Record<string, unknown>;
+    };
+}
+/** Server-computed report footer totals keyed by column field. */
+type AXPReportTableSummaryResult = Record<string, number | null>;
+interface AXPReportSummaryOptions {
+    field: string;
+    operation: 'sum' | 'avg' | 'count' | 'min' | 'max';
+    displayIn: 'groupFooter' | 'reportFooter';
+}
+interface AXPConditionalFormatRule {
+    field: string;
+    condition: '>' | '<' | '=' | '!=' | 'contains';
+    value: any;
+    style: {
+        color?: string;
+        backgroundColor?: string;
+        fontWeight?: 'normal' | 'bold';
+    };
+}
+interface AXPReportHeaderFooter {
+    title?: string;
+    logoUrl?: string;
+    showDate?: boolean;
+    showParameters?: boolean;
+    customHtml?: string;
+}
+/**
+ * Layout switcher options for UI components
+ */
+interface AXPLayoutSwitcherOption {
+    id: string;
+    title: string;
+    icon?: string;
+    type: AXPReportLayoutType;
+}
+/**
+ * Runtime layout selection state
+ */
+interface AXPReportLayoutState {
+    reportId: string;
+    activeLayoutId: string;
+    availableLayouts: AXPLayoutSwitcherOption[];
+}
+/**
+ * Layout validation result
+ */
+interface AXPLayoutValidationResult {
+    isValid: boolean;
+    errors: string[];
+    layoutId: string;
+}
+/**
+ * Data source resolution result for a specific layout
+ */
+interface AXPLayoutDataSourceResolution {
+    layoutId: string;
+    dataSource: AXPReportDataSource;
+    source: 'layout' | 'report' | 'none';
+}
+/**
+ * Layout execution context with resolved data source
+ */
+interface AXPLayoutExecutionContext {
+    reportId: string;
+    layoutId: string;
+    dataSource: AXPReportDataSource;
+    filters: AXPFilterClause;
+    skip?: number;
+    take?: number;
+    /** Runtime/user sort — platform shape `{ name, dir }`. */
+    sort?: AXPQuerySort[];
+}
+type AXPExecutionReportResult = {
+    type: 'table';
+    items: Record<string, unknown>[];
+    total: number;
+    summary?: AXPReportTableSummaryResult;
+} | {
+    type: 'chart';
+    data: Record<string, unknown>;
+} | {
+    type: 'cards';
+    items: Record<string, unknown>[];
+} | {
+    type: 'custom';
+    data: unknown;
+} | {
+    type: 'pdf';
+    url?: string;
+    base64?: string;
+    blob?: Blob;
+    filename?: string;
+};
+type AXPExecutionReportCommandResult = AXPReportLayout & {
+    data: AXPExecutionReportResult;
+};
+interface AXPExecutionReportCommand extends AXPCommand<AXPLayoutExecutionContext, AXPExecutionReportCommandResult> {
+}
+/**
+ * Report execution status and metadata
+ */
+interface AXPReportExecutionStatus {
+    reportId: string;
+    layoutId: string;
+    status: 'pending' | 'executing' | 'completed' | 'failed' | 'cancelled';
+    startTime: Date;
+    endTime?: Date;
+    duration?: number;
+    recordCount?: number;
+    error?: AXPReportExecutionError;
+}
+/**
+ * Detailed error information for report execution
+ */
+interface AXPReportExecutionError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    stack?: string;
+}
+/**
+ * Report execution request with options
+ */
+interface AXPReportExecutionRequest {
+    reportId: string;
+    layoutId: string;
+    parameters: Record<string, unknown>;
+    options?: AXPReportExecutionOptions;
+}
+/**
+ * Options for report execution
+ */
+interface AXPReportExecutionOptions {
+    timeout?: number;
+    priority?: 'low' | 'normal' | 'high';
+    cache?: boolean;
+    cacheTimeout?: number;
+}
+
+declare function reportEntityFactory(): Promise<AXPEntity | null>;
+
+declare function reportCategoryEntityFactory(): Promise<AXPEntity | null>;
+
+export { AXMPermissionsKeys, AXPReportManagementFeatureKeys, AXPReportManagementMenuKeys, RootConfig, reportCategoryEntityFactory, reportEntityFactory };
+export type { AXPAggregatedDataSource, AXPAggregation, AXPChartAxisConfig, AXPChartDataMapping, AXPChartInteractivity, AXPChartStyling, AXPConditionalFormatRule, AXPCustomDataSource, AXPDataTransformation, AXPExecutionReportCommand, AXPExecutionReportCommandResult, AXPExecutionReportResult, AXPLayoutDataSourceResolution, AXPLayoutExecutionContext, AXPLayoutSwitcherOption, AXPLayoutValidationResult, AXPQueryDataSource, AXPReportCategory, AXPReportChartLayout, AXPReportChartOptions, AXPReportColumn, AXPReportColumnInteractivity, AXPReportDataSource, AXPReportDefinition, AXPReportDrillDownConfig, AXPReportExecutionError, AXPReportExecutionOptions, AXPReportExecutionRequest, AXPReportExecutionStatus, AXPReportGroupByDefinition, AXPReportHeaderFooter, AXPReportLayout, AXPReportLayoutAction, AXPReportLayoutDefinition, AXPReportLayoutState, AXPReportLayoutType, AXPReportParameter, AXPReportParameterBinding, AXPReportParameterGroup, AXPReportPdfLayout, AXPReportPdfOptions, AXPReportSummaryOptions, AXPReportTableLayout, AXPReportTableLayoutRowAction, AXPReportTableSummaryResult, AXPTableOptions, AXPTransformedDataSource };