bways-report 0.1.0

package/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="bways-report" />
+export * from './public-api';

package/lib/core/errors/index.d.ts

@@ -0,0 +1 @@
+export { ReportDefinitionError, ComponentNotRegisteredError, DataSourceError, SchemaVersionError, AdapterNotProvidedError, } from './reporting-errors';

package/lib/core/errors/reporting-errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reporting library error types.
+ *
+ * Each error type has a distinct class for targeted catching
+ * and clear stack traces.
+ */
+/**
+ * Thrown when a report definition fails validation.
+ */
+export declare class ReportDefinitionError extends Error {
+    readonly reportId?: string | undefined;
+    constructor(message: string, reportId?: string | undefined);
+}
+/**
+ * Thrown when a component type is not found in the registry.
+ */
+export declare class ComponentNotRegisteredError extends Error {
+    readonly componentType: string;
+    constructor(componentType: string);
+}
+/**
+ * Thrown when a data source execution fails.
+ */
+export declare class DataSourceError extends Error {
+    readonly dataSourceId?: string | undefined;
+    constructor(message: string, dataSourceId?: string | undefined);
+}
+/**
+ * Thrown when a report definition's schema version is not supported.
+ */
+export declare class SchemaVersionError extends Error {
+    readonly currentVersion: number;
+    readonly supportedVersion: number;
+    constructor(currentVersion: number, supportedVersion: number, customMessage?: string);
+}
+/**
+ * Thrown when a required adapter/provider is not configured.
+ */
+export declare class AdapterNotProvidedError extends Error {
+    readonly adapterName: string;
+    constructor(adapterName: string);
+}

package/lib/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from './models';
+export * from './registry';
+export * from './tokens';
+export * from './errors';
+export * from './validation';
+export * from './services';
+export * from './utilities';

package/lib/core/models/component-event.model.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Event and action definitions for report components.
+ *
+ * Events describe what happened (user interaction).
+ * Actions describe what should happen in response (command pattern).
+ */
+/**
+ * Binds a component event to an action.
+ *
+ * Example:
+ * ```json
+ * {
+ *   "event": "change",
+ *   "action": { "type": "reload-data", "target": "cityDropdown" }
+ * }
+ * ```
+ */
+export interface ComponentEventDefinition {
+    /** The DOM/component event name (e.g., 'change', 'click', 'blur'). */
+    event: string;
+    /** The action to execute when the event fires. */
+    action: ComponentActionDefinition;
+}
+/**
+ * Describes a command to execute in response to a component event.
+ *
+ * Actions are declarative — the runtime engine interprets them.
+ * This avoids arbitrary function references in metadata.
+ */
+export interface ComponentActionDefinition {
+    /** Action type identifier (e.g., 'reload-data', 'set-value', 'navigate', 'execute-report'). */
+    type: string;
+    /** Target component ID or key this action affects. */
+    target?: string;
+    /** Additional action parameters. */
+    params?: Record<string, unknown>;
+}

package/lib/core/models/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for all core domain models.
+ */
+export type { ReportDefinition, ReportSummary, ReportPermissionDefinition, } from './report-definition.model';
+export type { ReportComponentDefinition, ComponentBindingDefinition, ComponentDataSourceDefinition, VisibilityDefinition, } from './report-component.model';
+export type { ReportParameterDefinition, } from './report-parameter.model';
+export type { ReportDataSourceDefinition, DataSourceCacheDefinition, } from './report-datasource.model';
+export type { ReportGridDefinition, GridColumnDefinition, GridOptionsDefinition, } from './report-grid.model';
+export type { ReportLayoutDefinition, ComponentLayoutDefinition, } from './report-layout.model';
+export type { ValidationDefinition, } from './validation.model';
+export type { ComponentEventDefinition, ComponentActionDefinition, } from './component-event.model';

package/lib/core/models/report-component.model.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Report component definition — the metadata for a single UI element
+ * that appears on a report page.
+ *
+ * The `type` field is the registry key used to resolve the Angular component
+ * at runtime via `ComponentRegistry`. This avoids hard-coding component types
+ * in the renderer.
+ */
+import { ComponentLayoutDefinition } from './report-layout.model';
+import { ValidationDefinition } from './validation.model';
+import { ComponentEventDefinition } from './component-event.model';
+/**
+ * Binding configuration for connecting a component to a data source or parameter.
+ */
+export interface ComponentBindingDefinition {
+    /** The data source ID this component reads from. */
+    dataSourceId?: string;
+    /** The field within the data source to bind to (for display components). */
+    field?: string;
+    /** The parameter key this component writes to (for input components). */
+    parameterKey?: string;
+}
+export type DropdownSourceType = 'static' | 'table' | 'procedure' | 'master';
+/**
+ * Data source configuration for components that load their own data
+ * (e.g., dropdowns loading options from database tables, stored procedures, or master data).
+ */
+export interface ComponentDataSourceDefinition {
+    /** Source type: 'static' | 'table' | 'procedure' | 'master' */
+    sourceType?: DropdownSourceType;
+    /** Database schema, e.g. 'dbo' (defaults to 'dbo'). */
+    schema?: string;
+    /** Database table, view, or stored procedure name (e.g. 'Customers' or 'usp_GetBranches'). */
+    entityName?: string;
+    /** Master data name for legacy master data provider resolution. */
+    masterName?: string;
+    /** Display field name in the returned data items (e.g. 'CustomerName'). */
+    displayField?: string;
+    /** Value field name in the returned data items (e.g. 'CustomerID'). */
+    valueField?: string;
+    /** Optional static filter parameters (e.g. { isActive: 1 }). */
+    filter?: Record<string, unknown>;
+    /** Stored procedure parameter mappings (e.g. { '@BranchId': '{{branchSelect}}', '@ActiveOnly': true }). */
+    parameterMappings?: Record<string, string | number | boolean>;
+    /** Keys of other form components whose values this data source depends on (for Cascading Dropdowns). */
+    dependsOn?: string[];
+    /** Cache time-to-live in seconds (default 300s). */
+    cacheTtl?: number;
+}
+/**
+ * Controls when a component is visible based on other component values.
+ */
+export interface VisibilityDefinition {
+    /** The component key whose value determines visibility. */
+    dependsOn: string;
+    /** The operator for the condition. */
+    operator: 'equals' | 'notEquals' | 'contains' | 'greaterThan' | 'lessThan' | 'isNotEmpty' | 'isEmpty';
+    /** The value to compare against. */
+    value?: unknown;
+}
+/**
+ * Full metadata definition for a single component on a report page.
+ *
+ * This is the core building block of a `ReportDefinition`.
+ */
+export interface ReportComponentDefinition {
+    /** Unique identifier for this component instance. */
+    id: string;
+    /** Registry key — maps to an Angular component via `ComponentRegistry`. */
+    type: string;
+    /** Form control key / parameter binding name. */
+    key?: string;
+    /** Display label (or translation key). */
+    label?: string;
+    /** Render order (lower = first). */
+    order?: number;
+    /** Position within the report layout grid. */
+    layout?: ComponentLayoutDefinition;
+    /** Component-specific configuration (e.g., placeholder, format, options). */
+    properties?: Record<string, unknown>;
+    /** Data binding configuration. */
+    binding?: ComponentBindingDefinition;
+    /** Validation rules. */
+    validation?: ValidationDefinition;
+    /** Data source for this component's options/data. */
+    dataSource?: ComponentDataSourceDefinition;
+    /** Event → action bindings. */
+    events?: ComponentEventDefinition[];
+    /** Conditional visibility rules. */
+    visibility?: VisibilityDefinition;
+    /** Whether this component is enabled. Defaults to `true`. */
+    enabled?: boolean;
+    /** CSS class names to add to the component wrapper. */
+    cssClass?: string;
+}

package/lib/core/models/report-datasource.model.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Report data source definitions.
+ *
+ * A data source describes how to fetch data for the report's result grid.
+ * The actual fetching is done by the host application through the
+ * `ReportDataSourceAdapter` contract.
+ */
+/**
+ * Defines a single data source for the report.
+ */
+export interface ReportDataSourceDefinition {
+    /** Unique identifier for this data source. */
+    id: string;
+    /** Human-readable name for the data source. */
+    name: string;
+    /** Endpoint identifier, stored procedure name, or query reference. */
+    endpoint: string;
+    /** HTTP method or execution method hint. */
+    method?: 'GET' | 'POST' | 'STORED_PROCEDURE' | 'CUSTOM';
+    /**
+     * Parameter keys that this data source requires.
+     * These are resolved from the report's current parameter values
+     * before calling the `ReportDataSourceAdapter`.
+     */
+    parameterKeys?: string[];
+    /** Whether to automatically execute this data source on report load. */
+    autoExecute?: boolean;
+    /** Caching strategy. */
+    cache?: DataSourceCacheDefinition;
+}
+/**
+ * Caching configuration for a data source.
+ */
+export interface DataSourceCacheDefinition {
+    /** Whether caching is enabled for this data source. */
+    enabled: boolean;
+    /** Cache duration in seconds. */
+    ttlSeconds?: number;
+}

package/lib/core/models/report-definition.model.d.ts

@@ -0,0 +1,100 @@
+/**
+ * ReportDefinition — the central domain object.
+ *
+ * A `ReportDefinition` is a complete, versioned, serializable description
+ * of a report page. It is the single source of truth for both the
+ * Designer and the Runtime.
+ *
+ * Key principle: **A report is data, not Angular source code.**
+ * The metadata is saved/loaded as JSON. Angular dynamically constructs
+ * the required controls, layout, and bindings at runtime.
+ */
+import { ReportComponentDefinition } from './report-component.model';
+import { ReportParameterDefinition } from './report-parameter.model';
+import { ReportDataSourceDefinition } from './report-datasource.model';
+import { ReportGridDefinition } from './report-grid.model';
+import { ReportLayoutDefinition } from './report-layout.model';
+/**
+ * Permission settings for a report.
+ */
+export interface ReportPermissionDefinition {
+    /** Roles that can view/execute this report. */
+    viewRoles?: string[];
+    /** Roles that can edit this report in the designer. */
+    editRoles?: string[];
+    /** Whether this report is publicly accessible. */
+    isPublic?: boolean;
+}
+/**
+ * Summary information for listing reports (without full definition).
+ */
+export interface ReportSummary {
+    /** Unique report identifier. */
+    id: string;
+    /** Report display name. */
+    name: string;
+    /** Brief description. */
+    description?: string;
+    /** Category or group for organizing reports. */
+    category?: string;
+    /** Current version number. */
+    version: number;
+    /** Whether the report is published (vs. draft). */
+    isPublished: boolean;
+    /** ISO date of last modification. */
+    lastModified?: string;
+    /** User who last modified. */
+    lastModifiedBy?: string;
+}
+/**
+ * Complete report definition — the source of truth.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "sales-register",
+ *   "name": "Sales Register",
+ *   "schemaVersion": 1,
+ *   "version": 1,
+ *   "layout": { "columns": 4, "gap": 16 },
+ *   "components": [...],
+ *   "parameters": [...],
+ *   "dataSources": [...],
+ *   "grid": { ... }
+ * }
+ * ```
+ */
+export interface ReportDefinition {
+    /** Unique report identifier. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Brief description. */
+    description?: string;
+    /** Metadata schema version — used for migration. */
+    schemaVersion: number;
+    /** Report content version — incremented on each save. */
+    version: number;
+    /** Category or group for organizing reports. */
+    category?: string;
+    /** Page layout configuration. */
+    layout: ReportLayoutDefinition;
+    /** Components (controls, buttons, display elements) on this report page. */
+    components: ReportComponentDefinition[];
+    /** Parameters that bridge inputs to data sources. */
+    parameters: ReportParameterDefinition[];
+    /** Data sources for executing queries. */
+    dataSources: ReportDataSourceDefinition[];
+    /** Result grid definition. */
+    grid?: ReportGridDefinition;
+    /** Access control settings. */
+    permissions?: ReportPermissionDefinition;
+    /** Custom metadata for host-specific extensions. */
+    metadata?: Record<string, unknown>;
+    /** ISO date of creation. */
+    createdAt?: string;
+    /** ISO date of last modification. */
+    updatedAt?: string;
+    /** User who last modified. */
+    updatedBy?: string;
+}

package/lib/core/models/report-grid.model.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Report grid definitions.
+ *
+ * Describes the logical structure of the result grid — columns, fields,
+ * formatting, sorting, and filtering. This is **not** a specific grid
+ * library's API. The `ReportGridBridgeComponent` translates this into
+ * whatever the host's grid component (BWays-grid, AG Grid, etc.) expects.
+ */
+/**
+ * Defines the result grid for a report.
+ */
+export interface ReportGridDefinition {
+    /** The data source ID that provides data for this grid. */
+    dataSourceId: string;
+    /** Column definitions. */
+    columns: GridColumnDefinition[];
+    /** Grid-level options. */
+    options?: GridOptionsDefinition;
+}
+/**
+ * Defines a single column in the result grid.
+ */
+export interface GridColumnDefinition {
+    /** The field name in the data row object. */
+    field: string;
+    /** Display label for the column header. */
+    label: string;
+    /** Column data type — used for formatting and sorting. */
+    dataType?: 'string' | 'number' | 'date' | 'boolean' | 'currency';
+    /** Display format (e.g., 'dd/MM/yyyy' for dates, '1.2-2' for numbers). */
+    format?: string;
+    /** Column width (CSS value, e.g., '150px', '20%'). */
+    width?: string;
+    /** Whether this column is sortable. Defaults to `true`. */
+    sortable?: boolean;
+    /** Whether this column is filterable. Defaults to `false`. */
+    filterable?: boolean;
+    /** Text alignment. */
+    align?: 'left' | 'center' | 'right';
+    /** Whether this column is visible. Defaults to `true`. */
+    visible?: boolean;
+    /** Whether this column is pinned/frozen. */
+    pinned?: 'left' | 'right' | false;
+    /** Column display order (lower = first). */
+    order?: number;
+    /** Aggregate function to display in a footer row. */
+    aggregate?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'none';
+}
+/**
+ * Grid-level options.
+ */
+export interface GridOptionsDefinition {
+    /** Number of rows per page. */
+    pageSize?: number;
+    /** Whether pagination is enabled. */
+    pagination?: boolean;
+    /** Whether row selection is enabled. */
+    selectable?: boolean;
+    /** Selection mode when selectable is true. */
+    selectionMode?: 'single' | 'multiple';
+    /** Whether to show row numbers. */
+    showRowNumbers?: boolean;
+    /** Whether to allow column reordering. */
+    allowColumnReorder?: boolean;
+    /** Whether to allow exporting. */
+    allowExport?: boolean;
+    /** Export formats to offer. */
+    exportFormats?: ('csv' | 'excel' | 'pdf')[];
+    /** Whether to show a footer row with aggregates. */
+    showFooter?: boolean;
+    /** Height of the grid (CSS value). */
+    height?: string;
+}

package/lib/core/models/report-layout.model.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Layout definitions for report pages and individual components.
+ *
+ * Layout metadata uses **logical** values (rows, columns, spans) —
+ * not CSS class strings like `col-md-3`. The renderer translates
+ * logical layout to CSS Grid at runtime.
+ */
+/**
+ * Describes the overall page layout for a report.
+ */
+export interface ReportLayoutDefinition {
+    /** Number of grid columns the report page uses. */
+    columns: number;
+    /** Gap between grid cells in pixels. */
+    gap?: number;
+    /** Optional padding around the report container in pixels. */
+    padding?: number;
+    /** Layout direction. Defaults to 'ltr'. */
+    direction?: 'ltr' | 'rtl';
+}
+/**
+ * Describes how a single component is positioned within the report layout grid.
+ */
+export interface ComponentLayoutDefinition {
+    /** Grid row placement (1-based). */
+    row?: number;
+    /** Grid column placement (1-based). */
+    column?: number;
+    /** Number of columns this component spans. */
+    columnSpan?: number;
+    /** Number of rows this component spans. */
+    rowSpan?: number;
+    /** Explicit width override (CSS value, e.g., '200px', '50%'). */
+    width?: string;
+    /** Explicit height override (CSS value). */
+    height?: string;
+    /** Minimum height override (CSS value, e.g., '60px'). */
+    minHeight?: string;
+    /** Maximum height override (CSS value, e.g., '300px'). */
+    maxHeight?: string;
+    /** Forces this component to start on a new separate row in the grid. Defaults to false. */
+    newRow?: boolean;
+}

package/lib/core/models/report-parameter.model.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Report parameter definitions.
+ *
+ * Parameters are the values that report input controls write to
+ * and that data source queries read from. They serve as the bridge
+ * between the user's form inputs and the backend query.
+ */
+/**
+ * Defines a single report parameter.
+ */
+export interface ReportParameterDefinition {
+    /** Unique key identifying this parameter. */
+    key: string;
+    /** Display name for the parameter. */
+    label: string;
+    /** Data type of the parameter value. */
+    dataType: 'string' | 'number' | 'date' | 'boolean' | 'array';
+    /** Default value if the user doesn't provide one. */
+    defaultValue?: unknown;
+    /** Whether this parameter must have a value before executing the report. */
+    required?: boolean;
+}

package/lib/core/models/validation.model.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Validation rule definitions for report component controls.
+ *
+ * Pure data — no Angular dependencies. The `createValidators()` function
+ * in the validation module converts these into Angular `ValidatorFn[]`.
+ */
+/**
+ * Describes validation constraints for a single report component.
+ *
+ * Each property maps to a standard Angular validator.
+ * Custom validators can be referenced by name via `custom`.
+ */
+export interface ValidationDefinition {
+    /** Whether the field is required. */
+    required?: boolean;
+    /** Minimum numeric value (for number inputs). */
+    min?: number;
+    /** Maximum numeric value (for number inputs). */
+    max?: number;
+    /** Minimum string length. */
+    minLength?: number;
+    /** Maximum string length. */
+    maxLength?: number;
+    /** Regex pattern the value must match. */
+    pattern?: string;
+    /** Name of a custom validator registered by the host application. */
+    custom?: string;
+    /** User-facing message overrides, keyed by validator name. */
+    messages?: Record<string, string>;
+}

package/lib/core/registry/component-category.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Component category types.
+ *
+ * Categories organize components in the Designer's palette
+ * and help the runtime understand a component's role.
+ */
+/**
+ * Predefined component categories.
+ *
+ * - `input` — Form controls that accept user input (text, dropdown, date, etc.)
+ * - `action` — Buttons and triggers (search, reset, export)
+ * - `display` — Read-only display elements (labels, KPIs, summaries)
+ * - `data` — Data-bound components (grids, charts)
+ * - `layout` — Structural components (sections, tabs, dividers)
+ */
+export type ComponentCategory = 'input' | 'action' | 'display' | 'data' | 'layout';

package/lib/core/registry/component-registry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ComponentRegistry — the scalable alternative to a giant `@switch` block.
+ *
+ * Instead of hard-coding component types in the renderer template:
+ * ```html
+ * @switch (comp.type) {
+ *   @case ('input') { ... }
+ *   @case ('dropdown') { ... }
+ *   ...100 more cases...
+ * }
+ * ```
+ *
+ * The registry maps type strings to Angular component classes:
+ * ```typescript
+ * registry.register({ type: 'input', component: RptInputComponent, ... });
+ * const meta = registry.resolve('input');
+ * // Use meta.component with ngComponentOutlet
+ * ```
+ *
+ * **Host override**: The host ERP can register its own component for any type.
+ * If the host registers `type: 'dropdown'` with its PrimeNG-based dropdown,
+ * that component wins over the library's built-in dropdown.
+ */
+import { Type } from '@angular/core';
+import { ComponentCategory } from './component-category';
+import { PropertyDefinition } from './property-definition.model';
+import { ReportComponentDefinition } from '../models/report-component.model';
+import * as i0 from "@angular/core";
+/**
+ * Metadata describing a registered component type.
+ */
+export interface ReportingComponentMeta {
+    /** Unique type key (e.g., 'input', 'dropdown', 'date', 'customer-selector'). */
+    type: string;
+    /** Human-readable name for the Designer palette. */
+    displayName: string;
+    /** Category for grouping in the Designer palette. */
+    category: ComponentCategory;
+    /** Optional icon identifier for the Designer palette. */
+    icon?: string;
+    /**
+     * Factory function that creates a default `ReportComponentDefinition`
+     * for this type. Used when dragging a new component onto the canvas.
+     */
+    createDefaultConfig(): Partial<ReportComponentDefinition>;
+    /** The Angular component class to render at runtime. */
+    component: Type<unknown>;
+    /**
+     * Property schema — describes configurable properties for the
+     * Designer's property editor.
+     */
+    propertySchema: PropertyDefinition[];
+}
+/**
+ * Central registry for all report component types.
+ *
+ * The registry is a simple `Map<string, ReportingComponentMeta>`.
+ * It does not use DI for individual components — DI is used to
+ * provide the registry itself.
+ *
+ * **Registration order**: Last registration wins. This allows the host
+ * application to override built-in components by registering after
+ * the library's built-in registration.
+ */
+export declare class ComponentRegistry {
+    private readonly registry;
+    /**
+     * Register a component type.
+     *
+     * If a component with the same `type` is already registered,
+     * it is replaced. This enables host overrides.
+     *
+     * @param meta - Component metadata including the Angular component class.
+     */
+    register(meta: ReportingComponentMeta): void;
+    /**
+     * Resolve a component type to its metadata.
+     *
+     * @param type - The component type key.
+     * @returns The metadata, or `undefined` if not registered.
+     */
+    resolve(type: string): ReportingComponentMeta | undefined;
+    /**
+     * Check whether a component type is registered.
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered component metadata entries.
+     */
+    getAll(): ReportingComponentMeta[];
+    /**
+     * Get registered components filtered by category.
+     */
+    getByCategory(category: ComponentCategory): ReportingComponentMeta[];
+    /**
+     * Get all registered type keys.
+     */
+    getRegisteredTypes(): string[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComponentRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ComponentRegistry>;
+}

package/lib/core/registry/index.d.ts

@@ -0,0 +1,4 @@
+export { ComponentRegistry } from './component-registry';
+export type { ReportingComponentMeta } from './component-registry';
+export type { ComponentCategory } from './component-category';
+export type { PropertyDefinition, PropertyOption } from './property-definition.model';