bways-report 0.1.9 → 0.2.0

package/README.md

@@ -1,448 +1,595 @@
-# BWays-Report — Integration & Developer Guide
+# BWays-Report — Enterprise Reporting & Visual Page Builder
 
-`bways-report` is an enterprise reporting platform and visual drag-and-drop page builder for Angular 18+ business & ERP applications with NestJS / SQL Server.
+[![npm version](https://img.shields.io/npm/v/bways-report.svg)](https://www.npmjs.com/package/bways-report)
+[![license](https://img.shields.io/badge/License-Proprietary-blue.svg)](LICENSE)
+[![Angular](https://img.shields.io/badge/Angular-18%2B%20%7C%2019%2B-DD0031.svg)](https://angular.io)
+
+`bways-report` is an enterprise-grade reporting engine and visual drag-and-drop page builder for Angular 18+ business & ERP applications with NestJS / Microsoft SQL Server.
 
-It empowers developers and business users to visually design reporting pages with filters, lookup dropdowns, metric cards, charts, and data grids. Report configurations are saved as clean JSON metadata (`ReportDefinition`), and the runtime engine dynamically generates reactive forms, controls, queries, and live grid views on the fly.
+It eliminates the need to manually code components, reactive forms, date pickers, dropdowns, and data grids for every single report. Instead, reports are designed visually in the browser, stored permanently in the database as clean JSON metadata, and rendered dynamically at runtime with live stored procedures, server-side execution, and data export.
 
 ---
-[![npm version](https://img.shields.io/npm/v/bways-report.svg)](https://www.npmjs.com/package/bways-report)
-[![license](https://img.shields.io/badge/License-Proprietary-blue.svg)](LICENSE)
-[![Changelog](https://img.shields.io/badge/Changelog-v0.2.0-blue.svg)](CHANGELOG.md)
+
+## Why bways-report? (GUI vs. Manual Coding)
+
+In traditional ERP and business applications, creating 50 reports requires:
+- Generating 50 separate Angular components (`ng g c ...`)
+- Writing thousands of lines of boilerplate HTML forms, labels, validation, and CSS grids
+- Hardcoding TypeScript column definitions, formatting, sorting, and pagination
+- Recompiling, testing, and **re-deploying the frontend application** for every column or label change requested by clients
+
+### With `bways-report`:
+| Feature | Traditional Coding | With `bways-report` |
+| :--- | :--- | :--- |
+| **New Report Creation** | Hours of coding `.ts`, `.html`, `.css` | **2 minutes** in visual drag-and-drop designer |
+| **Component Files** | 1 component per report (50 reports = 50 files) | **0 new files**. Handled dynamically by a single generic viewer |
+| **Client Change Requests** | Edit code, re-build Angular bundle, redeploy | Edit in GUI, click **Save**. Changes are live instantly! |
+| **Persistence** | Hardcoded templates | Stored in SQL Server (`CNFREPORTDEF`) |
+| **Data Export** | Manual Excel/CSV export logic | Built-in 1-click Excel, CSV, and Print exports |
+
 ---
 
-## What's New in v0.2.0
+## How It Works (The Lifecycle)
 
-- **1 Config Object + 3 Drop-in Components**: Eliminate boilerplate adapters with `BwaysReportConfig` and drop-in tags.
-- **`<bways-report-builder>`**: Drop-in visual designer shell with width/height controls, starter blueprints, and save flow.
-- **`<bways-report-page>`**: Live runtime form & dynamic grid page rendered automatically from a report slug.
-- **`<bways-report-menu>` & `injectReportMenu()`**: Responsive navigation menu (sidebar, navbar, dropdown) with search and category folding.
-- **`bwaysReportRoutes()`**: Declarative Angular routing for live report pages (`/reports/:slug`).
-- **Post-Save Interactive Modal**: Immediate live form preview with page routing settings (slug, menu group, publish toggle).
-- **CDK Overlay Viewport Flipping**: Zero clipping for searchable dropdowns inside cards and scroll containers.
-- **Quick Action ("+") & Inline Renaming**: Double-click report title to rename in place; `+` button to start fresh pages.
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. VISUAL DESIGNER (<rpt-designer>)                         │
+│    • Drag & drop inputs, date ranges, lookup dropdowns      │
+│    • Connect stored procedures & select output grid columns │
+│    • Click "Save" ───► Generates ReportDefinition JSON      │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ POST /api/reporting/reports
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. DATABASE STORAGE (SQL Server)                            │
+│    • Saved to table: CNFREPORTDEF                 │
+│    • Column DEFJSON: Stores the report JSON schema   │
+│    • Relational columns: CODE, NAME, VERSION, STATUS_CODE        │
+└──────────────────────────────┬──────────────────────────────┘
+                               │ GET /api/reporting/reports/:id
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. RUNTIME ENGINE (<rpt-report> or bwaysReportRoutes)       │
+│    • User opens route: /reports/:slug                    │
+│    • Fetches JSON schema from database                      │
+│    • Renders live Reactive Forms, Parameter Validation,     │
+│      UltraGrid, Charts, and Excel/CSV/Print export toolbar  │
+└─────────────────────────────────────────────────────────────┘
+```
 
 ---
 
 ## Table of Contents
 
-1. [Quick Start (5 Steps)](#1-quick-start-5-steps)
-   - [Step 1: Install](#step-1-install)
-   - [Step 2: Configure Once (`app.config.ts`)](#step-2-configure-once-appconfigts)
-   - [Step 3: Drop-in Builder Component](#step-3-drop-in-builder-component)
-   - [Step 4: Host Navigation Menu](#step-4-host-navigation-menu)
-   - [Step 5: Declarative Routes (`app.routes.ts`)](#step-5-declarative-routes-approutests)
-2. [Visual Designer Features](#2-visual-designer-features)
-   - [Single-Mode Technical Property Editor](#single-mode-technical-property-editor)
-   - [CDK Overlay Viewport Flip](#cdk-overlay-viewport-flip)
-   - [Post-Save Live Preview & Settings Dialog](#post-save-live-preview--settings-dialog)
-   - [Inline Double-Click Renaming](#inline-double-click-renaming)
-   - [Report Switcher & Quick New Page ("+")](#report-switcher--quick-new-page-)
-3. [Backend Contract Reference](#3-backend-contract-reference)
-4. [Dynamic Session Context & Auto-Parameter Binding](#4-dynamic-session-context--auto-parameter-binding)
-5. [Plugging in BWays-Grid (`UltraGridComponent`)](#5-plugging-in-bways-grid-ultragridcomponent)
-6. [Advanced Custom Adapters](#6-advanced-custom-adapters)
-7. [Theming & CSS Custom Properties](#7-theming--css-custom-properties)
-8. [Exporting Data (CSV & JSON)](#8-exporting-data-csv--json)
+1. [Installation](#1-installation)
+2. [Designer Configuration](#2-designer-configuration)
+3. [Declarative Routes (`app.routes.ts`) — Zero Component Code](#3-declarative-routes-approutests)
+4. [Component Usage Patterns](#4-component-usage-patterns)
+   - [Pattern A: Embed a Saved Report by ID (`<rpt-report [id]>`)](#pattern-a-embed-a-saved-report-by-id)
+   - [Pattern B: Embed from In-Memory JSON (`<rpt-report [report]>`)](#pattern-b-embed-from-in-memory-json)
+   - [Pattern C: Embed the Visual Designer (`<rpt-designer>`)](#pattern-c-embed-the-visual-designer)
+   - [Pattern D: Toggle View / Edit on the Same Page](#pattern-d-toggle-view--edit-on-the-same-page)
+5. [Database Persistence & SQL Schema](#5-database-persistence--sql-schema)
+6. [Save Confirmation & Host Notifications](#6-save-confirmation--host-notifications)
+7. [Data Grid & UltraGrid Integration](#7-data-grid--ultragrid-integration)
+8. [Backend API Contract](#8-backend-api-contract)
 
 ---
 
-## 1. Quick Start (5 Steps)
+## 1. Installation
 
-### Step 1: Install
+Install the package and its peer dependencies via npm:
 
 ```bash
-npm install bways-report bways-grid @angular/cdk
+npm install bways-report @angular/cdk
 ```
 
-> **Compatibility**: Angular 18+ or 19+ standalone architecture with Zone.js or Zoneless change detection.
+> **Requirements**: Angular 18+ or 19+ (standalone architecture). Compatible with both Zone.js and Zoneless change detection.
 
 ---
 
-### Step 2: Configure Once (`app.config.ts`)
+## 2. Designer Configuration
 
-Configure `provideBwaysReport()` with a single `BwaysReportConfig` object:
+### Configure inside the designer page
+
+Define a typed object in the page component and bind it through `[config]`. An embedded designer does not require `provideBwaysReport()` in `app.config.ts`. Register Angular's `provideHttpClient()` once in the host application so its authentication interceptors remain available.
 
 ```typescript
-// src/app/app.config.ts
-import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+// rpt-designer.component.ts
+import { Component } from '@angular/core';
+import { BwaysReportConfig, DesignerComponent } from 'bways-report';
+
+@Component({
+  selector: 'app-rpt-designer',
+  standalone: true,
+  imports: [DesignerComponent],
+  templateUrl: './rpt-designer.component.html',
+  styles: [`
+    :host {
+      display: flex;
+      flex-direction: column;
+      height: calc(100dvh - 64px);
+      min-height: 0;
+      min-width: 0;
+    }
+  `],
+})
+export class RptDesignerComponent {
+  readonly designerConfig: BwaysReportConfig = {
+    spEndpoint: '/api/reporting/procedures',
+    tablesEndpoint: '/api/reporting/tables',
+    executeEndpoint: '/api/reporting/execute',
+    lookupEndpoint: '/api/reporting/lookup',
+    session: { companyId: 101, branchId: 1 },
+    autoParameter: true,
+    components: ['formInputs', 'actionButtons'],
+    routeBase: 'reports',
+    defaultPageSize: 25,
+  };
+}
+```
+
+```html
+<!-- rpt-designer.component.html -->
+<rpt-designer [config]="designerConfig"></rpt-designer>
+```
+
+Give the designer page a definite height, as above, adjusting `64px` for your application header. Inside an existing flex layout, use `flex: 1; height: 100%; min-height: 0` on every page wrapper and `min-height: 0` on the parent flex work area. Canvas, preview and JSON then scroll inside the available height. A wrapper that grows with its content inside an `overflow: hidden` application shell clips the page instead.
+
+For an application embedding only the designer, the reporting-related bootstrap configuration is:
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
 import { provideHttpClient } from '@angular/common/http';
-import { provideRouter } from '@angular/router';
-import { provideBwaysReport, BwaysReportConfig } from 'bways-report';
-import { UltraGridComponent } from 'bways-grid';
-import { routes } from './app.routes';
-import { AuthService } from './services/auth.service';
-
-const reportConfig: BwaysReportConfig = {
-  // Backend Endpoints (only these 3-4 URLs needed)
-  spEndpoint:      'http://localhost:3000/api/reporting/procedures', // GET  -> SPs + parameters
-  tablesEndpoint:  'http://localhost:3000/api/reporting/tables',     // GET  -> Tables + columns
-  executeEndpoint: 'http://localhost:3000/api/reporting/execute',    // POST -> Query / SP execution
-  lookupEndpoint:  'http://localhost:3000/api/reporting/lookup',     // POST -> Dropdown master data / lookup (optional)
-  reportsEndpoint: 'http://localhost:3000/api/reporting/reports',    // Optional CRUD (defaults to localStorage)
-
-  // Visual Designer Configuration
-  components: ['formInputs', 'actionButtons', 'displayLabels'],      // Palette categories to show (default: all)
-  autoParameter: true,                                               // Auto-bind @BranchId, @CompanyId from session
-  session: () => inject(AuthService).currentSession(),               // Session source for autoParameter
-
-  // Live Pages & Data Grid
-  routeBase: 'reports',                                              // Live pages mount at /reports/:slug
-  grid: UltraGridComponent,                                          // UltraGrid from bways-grid (or built-in table)
-  defaultPageSize: 25,
-};
 
 export const appConfig: ApplicationConfig = {
-  providers: [
-    provideZoneChangeDetection({ eventCoalescing: true }),
-    provideHttpClient(),
-    provideRouter(routes),
-    provideBwaysReport(reportConfig),
-  ],
+  providers: [provideHttpClient()],
 };
 ```
 
----
+Retain your application's existing router, authentication interceptors, and other providers. Page configuration selects reporting URLs and tenant context; backend authorization remains the host application's responsibility.
 
-### Step 3: Drop-in Builder Component
+All fields are optional. Settings resolve in this order: library defaults, optional application defaults, `[config]`, then `[apiUrl]` for individual endpoint overrides. Omitted or undefined values inherit defaults. Arrays replace inherited arrays; an empty `components` array retains the existing meaning of unrestricted palette categories.
 
-Embed the full visual drag-and-drop report designer with one HTML tag:
+| Source | Scope | Overrides |
+| --- | --- | --- |
+| Library defaults | Built-in fallback settings | None |
+| `provideBwaysReport(...)` | Optional app-wide defaults, including separate viewers and menus | Library defaults |
+| `[config]="designerConfig"` | One designer, including preview and save review | Supplied app settings |
+| `[apiUrl]="apiUrls"` | Endpoint overrides for that designer | Supplied endpoint values from all other sources |
 
-```html
-<!-- src/app/pages/admin-reports/admin-reports.component.html -->
-<bways-report-builder
-  width="100%"
-  height="calc(100vh - 64px)"
-  (saved)="onReportSaved($event)"
-/>
-```
+For example, a page can configure all settings locally while overriding only report storage:
 
 ```typescript
-// src/app/pages/admin-reports/admin-reports.component.ts
-import { Component } from '@angular/core';
-import { BwaysReportBuilderComponent, ReportDefinition } from 'bways-report';
+// Inside the host component class; import BwaysReportApiUrls from bways-report.
+readonly apiUrls: BwaysReportApiUrls = {
+  reportsEndpoint: 'https://reports.example.com:9004/api/reporting/reports',
+};
+```
 
-@Component({
-  standalone: true,
-  imports: [BwaysReportBuilderComponent],
-  templateUrl: './admin-reports.component.html',
-})
-export class AdminReportsComponent {
-  onReportSaved(report: ReportDefinition): void {
-    console.log('Report saved and published:', report.name, report.slug);
-  }
-}
+```html
+<rpt-designer [config]="designerConfig" [apiUrl]="apiUrls"></rpt-designer>
 ```
 
----
+Each designer owns its effective settings, session resolution, preview, and storage adapters. Local `grid`, `chart`, `session`/`sessionProvider`, `apiEndpoints`, palette, routing, page size, timeout and date format follow this scope. Session sources support objects, signals, observables, factories using Angular `inject()`, and service classes. Replace the configuration object to update settings; session signals and observables update live. Existing draft edits are preserved and affected adapter caches are cleared. Setting `[config]="null"` restores application defaults while explicit `[apiUrl]` overrides remain active.
 
-### Step 4: Host Navigation Menu
+The public `<rpt-report-designer>` and `<rpt-designer-view>` facades also accept `[config]`. Configuration stays outside saved report JSON. Separately routed viewers and catalogs need their own application or route configuration; they do not inherit a destroyed designer page's settings. The save output is a notification after confirmed persistence and must not perform a second save.
 
-Display published reports in your host ERP navigation bar or sidebar:
+See the complete example in [rpt-designer.component.ts](../playground/src/app/page-designer/rpt-designer.component.ts) and [rpt-designer.component.html](../playground/src/app/page-designer/rpt-designer.component.html).
 
-#### Option A: Drop-in Component
-```html
-<!-- Sidebar variant with search filter and category folding -->
-<bways-report-menu variant="sidebar" />
+### Optional application defaults
+
+Keep endpoint defaults in a typed configuration object. Supply any subset: procedures, tables, execution, lookup, and report storage are independent capabilities. Missing discovery endpoints produce no entries; executing without an execution URL reports a configuration error. Report storage uses the built-in reporting API and writes to `dbo.CNFREPORTDEF`. A separate save URL is not required: omitted `reportsEndpoint` is inferred from the configured reporting endpoints, or defaults to `/api/reporting/reports`. Absolute URLs (including ports) are supported. Server failures remain visible and never fall back to localStorage.
+
+```typescript
+// src/app/config.ts
+import { BwaysReportConfig } from 'bways-report';
+import { environment } from '../environments/environment';
+
+const apiBase = environment.baseUrl;
+export const reportingConfig: BwaysReportConfig = {
+  spEndpoint: `${apiBase}/api/reporting/procedures`,
+  tablesEndpoint: `${apiBase}/api/reporting/tables`,
+  executeEndpoint: `${apiBase}/api/reporting/execute`,
+  lookupEndpoint: `${apiBase}/api/reporting/lookup`,
+  // Optional override; otherwise inferred automatically:
+  // reportsEndpoint: `${apiBase}/api/reporting/reports`,
+  autoParameter: true,
+};
+```
+
+```typescript
+// src/app/app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient } from '@angular/common/http';
+import { provideRouter } from '@angular/router';
+import { provideBwaysReport } from 'bways-report';
+import { reportingConfig } from './config';
+import { routes } from './app.routes';
 
-<!-- Or dropdown variant for top navigation bars -->
-<bways-report-menu variant="dropdown" />
+export const appConfig: ApplicationConfig = {
+  providers: [provideHttpClient(), provideRouter(routes), provideBwaysReport(reportingConfig)],
+};
 ```
 
-#### Option B: Reactive Signal (`injectReportMenu`)
+The legacy `apiBaseUrl` option remains available. `backendUrl` is not a configuration property.
+
+### Override endpoints for one designer
+
+Bind a `BwaysReportApiUrls` object to `[apiUrl]`. Every property is optional. Only supplied properties override the effective page configuration and app defaults; the configuration object and other designer instances stay unchanged.
+
 ```typescript
 import { Component } from '@angular/core';
-import { RouterLink, RouterLinkActive } from '@angular/router';
-import { injectReportMenu } from 'bways-report';
+import { BwaysReportApiUrls, DesignerComponent } from 'bways-report';
 
 @Component({
+  selector: 'app-custom-reports',
   standalone: true,
-  imports: [RouterLink, RouterLinkActive],
-  template: `
-    <nav class="erp-menu">
-      @for (group of menu(); track group.groupName) {
-        <div class="menu-group">
-          <h3>{{ group.groupName }}</h3>
-          @for (item of group.items; track item.id) {
-            <a [routerLink]="item.route" routerLinkActive="active">
-              {{ item.name }}
-            </a>
-          }
-        </div>
-      }
-    </nav>
-  `,
+  imports: [DesignerComponent],
+  template: '<rpt-designer [apiUrl]="reportApis" />',
 })
-export class NavigationSidebarComponent {
-  readonly menu = injectReportMenu();
+export class CustomReportsComponent {
+  reportApis: BwaysReportApiUrls = {
+    spEndpoint: '/api/custom/procedures',
+    // The other URLs inherit reportingConfig defaults.
+  };
 }
 ```
 
+You may provide only `tablesEndpoint`, only `reportsEndpoint`, or any combination of `spEndpoint`, `tablesEndpoint`, `executeEndpoint`, `lookupEndpoint`, `reportsEndpoint`, and `apisEndpoint`. Omitted or `undefined` properties inherit defaults. Supplied URLs must be non-empty strings.
+
+Overrides apply to discovery, lookups, live preview execution, and persistence inside that designer. Replace the object to change URLs; newly requested data uses the new configuration, and local adapter caches are cleared. Set `[apiUrl]="null"` to restore app defaults. Discovery choices refresh when the bound object changes; existing form selections are retained. Per-designer URLs are not stored in report JSON and do not change separately routed report viewers.
+
+`<rpt-report-designer>` and `<rpt-designer-view>` forward the same input. For NgModule applications, import the standalone `DesignerComponent` in your module's `imports` and use the same binding:
+
+```typescript
+@NgModule({ imports: [CommonModule, DesignerComponent] })
+export class ReportsModule {}
+```
+
 ---
 
-### Step 5: Declarative Routes (`app.routes.ts`)
+## 3. Declarative Routes (`app.routes.ts`)
 
-Add one line to your route definitions to enable dynamic live report pages:
+The helper supplies child routes. Mount them below your chosen path:
 
 ```typescript
-// src/app/app.routes.ts
 import { Routes } from '@angular/router';
 import { bwaysReportRoutes } from 'bways-report';
-import { AdminReportsComponent } from './pages/admin-reports/admin-reports.component';
 
 export const routes: Routes = [
-  // Admin visual designer route
-  { path: 'admin/reports', component: AdminReportsComponent },
-
-  // Live user reporting pages: /reports/:slug (e.g. /reports/sale-report)
   {
     path: 'reports',
-    children: bwaysReportRoutes({
-      // includeBuilderRoute: false, // Set true to include /reports/new and /reports/:slug/edit
-    }),
+    children: bwaysReportRoutes({ includeBuilder: true }),
   },
 ];
 ```
 
-When users click "Sale Report" in the menu, `/reports/sale-report` opens the **live interactive form** with reactive inputs and data grid without needing custom page components!
+This creates `/reports/:slug`, `/reports/new`, and `/reports/:slug/edit`. Builder routes are opt-in. The helper does not create a catalog route; embed `<bways-report-menu>` in your own catalog page if needed. Use `runtimeGuards` and `builderGuards` to apply host access policies, and `slugParam` to customize the identifier parameter. Backend authorization is also required.
 
 ---
 
-## 2. Visual Designer Features
+## 4. Component Usage Patterns
 
-### Single-Mode Technical Property Editor
-Eliminates confusing simplified/advanced toggles. Standardized on technical database terminology:
-- `Database Table / View`
-- `Stored Proc`
-- `Display Field (Visible Text)`
-- `Value Field (Stored Key)`
-- `Dependent On (Cascading Parent Field)`
+If you want to embed reports directly inside your existing dashboards or custom pages, use the standalone components:
 
-### CDK Overlay Viewport Flip
-Searchable selects (`<rpt-searchable-select>`) and comboboxes (`<rpt-dropdown>`) render inside Angular CDK Overlays attached to the document body. They automatically evaluate available viewport space and flip between `below-start`, `above-start`, `below-end`, and `above-end` to eliminate clipping inside cards and scrollable drawers.
+### Pattern A: Embed a Saved Report by ID
 
-### Post-Save Live Preview & Settings Dialog
-Saving a report in the builder automatically opens a two-column modal:
-- **Left Column**: Page settings (Display Name, URL Slug `/reports/:slug`, Menu Group, Publish to Menu toggle, and a Copy Route button).
-- **Right Column**: Live interactive form preview rendered via `<rpt-runtime>` allowing instant testing of validation and execution before publishing.
+Import `RptReportComponent` from `bways-report` and add it to your standalone component's `imports`. The simplest viewer template is:
 
-### Inline Double-Click Renaming
-Double-click the report title in the toolbar to edit it inline:
-- `Enter` saves the new name and suggests a URL slug.
-- `Escape` cancels edits.
-- `blur` persists the change.
-- Changes are pushed to the undo/redo history stack.
+```html
+<rpt-report [id]="'sales-report-id'" />
+```
 
-### Report Switcher & Quick New Page ("+")
-- **"+" Button**: Immediately instantiates a fresh blank canvas (with confirmation if unsaved changes exist).
-- **Report Switcher**: Dropdown populated from saved reports allowing rapid switching between report definitions.
+The ID is the saved `CNFREPORTDEF.CODE`. The viewer fetches its definition through the configured reporting API, which reads and parses `DEFJSON`; the browser does not connect to SQL Server directly. Configure `provideHttpClient()` and `provideBwaysReport({ reportsEndpoint: '/api/reporting/reports' })` in application or route providers, along with any required execution/session settings. A viewer does not inherit another designer's local `[config]`.
 
----
+You can also pass initial parameters and handle row clicks:
 
-## 3. Backend Contract Reference
+```html
+<!-- my-dashboard.component.html -->
+<rpt-report
+  [id]="'rpt-sales-summary'"
+  [parameters]="{ fromDate: '2026-01-01', branchId: 101 }"
+  (rowClick)="onRowClick($event)">
+</rpt-report>
+```
 
-| Endpoint | Method | Path | Request Format | Response Format |
-| :--- | :--- | :--- | :--- | :--- |
-| `spEndpoint` | `GET` | `/api/reporting/procedures` | None | `StoredProcedureSummary[]` |
-| `tablesEndpoint` | `GET` | `/api/reporting/tables` | None | `TableSummary[]` |
-| `executeEndpoint` | `POST` | `/api/reporting/execute` | `{ kind, name, schema, parameters, columns?, top? }` | `Record<string, unknown>[]` |
-| `reportsEndpoint` *(opt)* | `GET/POST/PUT/DELETE` | `/api/reporting/reports` | JSON `ReportDefinition` | `ReportSummary[]` / `ReportDefinition` |
+```typescript
+// my-dashboard.component.ts
+import { Component } from '@angular/core';
+import { RptReportComponent } from 'bways-report';
 
-### Stored Procedure Discovery Format
-```json
-[
-  {
-    "name": "usp_GetCustomerList",
-    "schema": "dbo",
-    "parameters": [
-      { "name": "@BranchId", "sqlType": "int", "required": true },
-      { "name": "@SearchTerm", "sqlType": "varchar", "required": false, "defaultValue": "" }
-    ]
+@Component({
+  selector: 'app-my-dashboard',
+  standalone: true,
+  imports: [RptReportComponent],
+  templateUrl: './my-dashboard.component.html',
+})
+export class MyDashboardComponent {
+  onRowClick(event: { row: Record<string, unknown> }): void {
+    console.log('User clicked invoice row:', event.row);
   }
-]
+}
 ```
 
-### Table Discovery Format
-```json
-[
-  {
-    "name": "Customers",
-    "schema": "dbo",
-    "type": "table",
-    "columns": [
-      { "name": "CustomerId", "sqlType": "int" },
-      { "name": "CustomerName", "sqlType": "nvarchar" }
-    ]
-  }
-]
-```
+---
 
-### Execution Request Format
-Supports both simplified and enterprise DTO contracts out-of-the-box:
-
-**Option A (Simplified contract):**
-```json
-{
-  "kind": "procedure",
-  "name": "usp_GetCustomerList",
-  "schema": "dbo",
-  "parameters": {
-    "BranchId": 1,
-    "SearchTerm": "Acme"
-  }
+### Pattern B: Embed from In-Memory JSON
+
+If your host project retrieves the report definition from its own custom service, database table, or static JSON file, pass the object directly:
+
+```html
+@if (reportSchema) {
+  <rpt-report [report]="reportSchema"></rpt-report>
 }
 ```
 
-**Option B (Enterprise DTO contract):**
-```json
-{
-  "dataSource": {
-    "id": "usp_GetCustomerList",
-    "type": "stored_procedure",
-    "name": "usp_GetCustomerList",
-    "schema": "dbo"
-  },
-  "parameters": {
-    "BranchId": 1
-  },
-  "sessionContext": {
-    "companyId": 101,
-    "branchId": 1
+```typescript
+import { Component, OnInit, inject } from '@angular/core';
+import { RptReportComponent, ReportDefinition } from 'bways-report';
+import { MyCustomApiService } from './my-custom-api.service';
+
+@Component({
+  standalone: true,
+  imports: [RptReportComponent],
+  template: `@if (reportSchema) { <rpt-report [report]="reportSchema" /> }`
+})
+export class CustomReportLoaderComponent implements OnInit {
+  private api = inject(MyCustomApiService);
+  reportSchema: ReportDefinition | null = null;
+
+  ngOnInit(): void {
+    this.api.fetchReportFromCustomDb('rpt-sales').subscribe((data) => {
+      // If data is stored as JSON text, parse it:
+      this.reportSchema = typeof data === 'string' ? JSON.parse(data) : data;
+    });
   }
 }
 ```
 
-### Dropdown Lookup Request Format (`lookupEndpoint`)
-Dropdowns with database data sources query `/api/reporting/lookup` (or fallback to `executeEndpoint`):
-```json
-{
-  "entityName": "Sel_UserWiseCompUnit",
-  "sourceType": "stored_procedure",
-  "schema": "dbo",
-  "valueField": "COMPUNIT_ID",
-  "displayField": "COMPUNIT_NAME",
-  "parameters": {}
-}
+---
+
+### Pattern C: Embed the Visual Designer
+
+Import `DesignerComponent` and `BwaysReportConfig` from `bways-report`. Add `DesignerComponent` to your standalone component's `imports`, or to the `imports` of your NgModule. These template bindings are component inputs, not additional Angular modules. Keep the page's configuration in its TypeScript file:
+
+```typescript
+// Inside the host component class.
+readonly designerConfig: BwaysReportConfig = {
+  reportsEndpoint: '/api/reporting/reports',
+  // Add discovery, execution, lookup and session settings as required.
+};
 ```
 
----
+Give the host a definite height, for example `height: calc(100dvh - 64px)`, plus `display: flex; flex-direction: column; min-height: 0`. Inside an existing bounded flex layout, use `flex: 1; height: 100%; min-height: 0` on the page wrapper so canvas, preview and JSON can scroll. Register `provideHttpClient()` once in the application.
 
-## 4. Dynamic Session Context & Auto-Parameter Binding
+#### Template 1: Automatic database-backed report selector
 
-When `autoParameter: true` is configured, parameters matching active ERP session keys are automatically populated and hidden from non-technical users:
+```html
+<!-- rpt-designer.component.html -->
+<rpt-designer
+  [config]="designerConfig"
+  (save)="onReportSaved($event)"
+/>
+```
 
-| Stored Procedure Parameter | Matching Session Keys |
-| :--- | :--- |
-| `@BranchId`, `@branch_id`, `@bid`, `@branchcode`, `@locationid` | `branchId`, `branch`, `locationId` |
-| `@CompanyId`, `@company_id`, `@cid`, `@companycode`, `@tenantid` | `companyId`, `company`, `tenantId` |
-| `@UserId`, `@user_id`, `@uid`, `@usercode`, `@operatorid` | `userId`, `user`, `loginUser` |
-| `@FinancialYearId`, `@fyear`, `@fiscalyear`, `@yearid` | `financialYearId`, `fYear` |
+The built-in toolbar selector requests `GET /api/reporting/reports` and displays the returned report summaries. Selecting an entry requests `GET /api/reporting/reports/:id`, where `id` maps to `CNFREPORTDEF.CODE`. The backend returns the parsed `DEFJSON` with authoritative ID, name and version metadata. These routes follow your configured `reportsEndpoint`.
+
+To initially open a particular saved report, add `[reportId]`:
+
+```html
+<rpt-designer
+  [config]="designerConfig"
+  [reportId]="'sales-report-id'"
+  (save)="onReportSaved($event)"
+/>
+```
+
+#### Template 2: Host supplies the selected report definition
+
+Use this when your application already fetches the saved report through its own service:
 
-Session values can be updated at runtime:
 ```typescript
-import { inject } from '@angular/core';
-import { ReportSessionContextService } from 'bways-report';
+// Import ReportDefinition from bways-report.
+selectedReport: ReportDefinition | null = null;
+// Assign the parsed, validated report returned by your host service.
+```
+
+```html
+@if (selectedReport) {
+  <rpt-designer
+    [config]="designerConfig"
+    [initialReport]="selectedReport"
+    (save)="onReportSaved($event)"
+  />
+}
+```
+
+`[initialReport]` accepts a complete `ReportDefinition` object, not a raw SQL row or an unparsed `DEFJSON` string. If your API returns `DEFJSON` as text, parse and validate it in your service and handle invalid JSON before assigning it. The standard backend already returns a parsed object. Use either `[reportId]` or `[initialReport]` as the loading source; when both are supplied, a non-null `[initialReport]` takes precedence.
+
+This supported template controls the selected definition; it does not replace the library toolbar's report list. The built-in list still uses `reportsEndpoint`.
+
+#### Planned host-controlled toolbar API (not implemented)
+
+The following is a proposed extension for applications that also want to supply the toolbar list and handle selection themselves. It will not compile with the current library:
+
+```html
+<!-- Proposed API only: reports and reportSelected are not available yet. -->
+<rpt-designer
+  [config]="designerConfig"
+  [reports]="savedReports"
+  [initialReport]="selectedReport"
+  (reportSelected)="loadReport($event)"
+  (save)="onReportSaved($event)"
+/>
+```
+
+Under this proposal, `savedReports` would contain `ReportSummary[]`, and `loadReport(reportId: string)` would retrieve the selected definition. Full report JSON would be fetched only after selection. There is currently no `[reportState]` input; use the supported `[initialReport]` input for a parsed definition.
+
+For both supported templates, `(save)` runs only after successful persistence. Use the handler for notifications or refreshing host data; do not save the same report a second time. Existing IDs require Update or Cancel confirmation before writing.
+
+---
+
+### Pattern D: Toggle View / Edit on the Same Page
 
-export class SessionWidget {
-  private readonly session = inject(ReportSessionContextService);
+You can allow administrators to view a report and switch to edit mode on the same screen:
 
-  onBranchSwitch(branchId: number): void {
-    this.session.setSessionParameter('branchId', branchId);
+```html
+<div class="toolbar">
+  @if (isAdmin) {
+    <button (click)="isEditMode = !isEditMode">
+      {{ isEditMode ? 'Exit Designer (View Mode)' : 'Edit Layout (Designer)' }}
+    </button>
   }
+</div>
+
+@if (isEditMode) {
+  <rpt-designer [reportId]="reportId" (save)="isEditMode = false"></rpt-designer>
+} @else {
+  <rpt-report [id]="reportId"></rpt-report>
 }
 ```
 
 ---
 
-## 5. Plugging in BWays-Grid (`UltraGridComponent`)
+## 5. Database Persistence & SQL Schema
+
+Reports are stored in `dbo.CNFREPORTDEF`. The backend creates this table at startup when it is absent. Its `dbo` alias types must already be installed in the target ERP database.
+
+`UTypeLongText1` must be valid for the `CODE` primary key. The complete report JSON needs `DEFJSON nvarchar(max)`: a finite ERP text alias cannot hold a full definition. Startup widens only this column for existing installations; the shared ERP alias types are retained. Other metadata respects the actual column limits (for example, `NAME` may allow only 10 characters). Oversized values produce a clear error in the review dialog without losing the draft.
+
+```sql
+IF OBJECT_ID(N'dbo.CNFREPORTDEF', N'U') IS NULL
+BEGIN
+    CREATE TABLE [dbo].[CNFREPORTDEF] (
+        [CODE] [dbo].[UTypeLongText1] PRIMARY KEY,
+        [NAME] [dbo].[UTypeShortText1] NULL,
+        [DESCRIPTION] [dbo].[UTypeLongText1] NULL,
+        [VERSION] [int] NULL,
+        [STATUS_CODE] [int] NULL,
+        [DEFJSON] nvarchar(max) NULL,
+        [SYSADD_DATETIME] [dbo].[UTypeDateTime] NULL,
+        [SYSCHNG_DATETIME] [dbo].[UTypeDateTime] NULL,
+        [SYSADD_LOGIN] [dbo].[UTypeUserLogin] NULL,
+        [SYSCHNG_LOGIN] [dbo].[UTypeUserLogin] NULL
+    );
+END;
+```
+
+The HTTP API keeps using `id`, `name`, `description`, `version`, `isPublished` and the complete report object. The backend maps these to `CODE`, `NAME`, `DESCRIPTION`, `VERSION`, `STATUS_CODE` and `DEFJSON`. Only `STATUS_CODE = 1` means published; `0` or `NULL` is treated as draft. Category, slug, layout, components and data sources stay in `DEFJSON`.
 
-`BWays-Report` provides first-class support for `bways-grid` (`v0.1.18+` / `v0.1.19+`). Pass `grid: UltraGridComponent` to `provideBwaysReport()`:
+Creation fills both audit timestamps and login columns; updates and publication preserve creation audit values and change only `SYSCHNG_*`. Audit logins come from the backend authorization policy's `userLogin`, or remain `NULL` if no authenticated login is supplied.
 
-- **Runtime `@Input()` Safety**: Dynamic grid bridging inspects component metadata (`ɵcmp.inputs`) before calling `ComponentRef.setInput()`, preventing Angular `NG0303` runtime template binding errors.
-- **Row Selection Alignment**: Row selection mode (`single` vs `multiple`) is passed cleanly through `config.rowSelection` and `config.selectionMode`, preserving full compatibility with `UltraGridComponent`.
-- **Circular Echo Suppression**: Grid state changes originating from user interaction are tracked to avoid re-triggering parent input cycles. Column menus, search inputs, and drag-handles stay open and focused without flicker.
-- **Filter State Preservation**: Preserves both `activeFilters` (checkboxes) and `conditionFilters` (expressions) across runtime updates and JSON serialization.
-- **Selective Layout Auto-Persistence**: Structural layout changes (column widths, pinning, grouping) persist immediately, while interactive data filtering is debounced to avoid undo stack pollution.
+For existing installations, run [create-report-definitions.sql](../../backend/sql/create-report-definitions.sql), then [migrate-report-definitions.sql](../../backend/sql/migrate-report-definitions.sql) in each intended ERP database. Migration copies missing records from the legacy tables, retains category in JSON, and preserves existing target records and source tables. It is not run automatically on server startup.
 
 ---
 
-## 6. Advanced Custom Adapters
+## 6. Save Confirmation & Host Notifications
+
+Clicking **Save** opens a review dialog before any write. Review the report ID, name, slug, description, category, menu group and publication status, then choose **Save Report** or **Save and Open**. Cancel leaves the draft unchanged. Each save makes a fresh ID check. If the ID exists, a confirmation panel identifies the saved report and version and offers **Update Report** (or **Update and Open**) and **Cancel**. No write occurs before Update. Cancel returns to the review with all entered details intact. During saving the controls are disabled; errors keep the dialog open for retry. Success and navigation happen only after the server confirms storage.
+
+The **Report ID** field accepts a custom ID (up to 100 letters, numbers, underscores or hyphens; start with a letter or number). **Random ID** generates a new value, and **Verify ID** checks for duplicates in the designer's configured storage and company. Editing the ID clears its verification result. Every save checks the ID again, including unchanged IDs and IDs previously checked with Verify ID. Failed verification keeps the draft open and performs no write.
+
+An available ID creates a new report using a create-only write. Any existing ID, including the original ID or an occupied custom ID, requires explicit update confirmation. Choosing an available custom ID leaves the original intact; review the URL slug for the new copy too. The bundled backend returns HTTP 409 if a new ID is taken after the check, or if a confirmed update targets a report that changed version or was deleted. The draft remains available and another save requires a fresh check and confirmation.
+
+The persistence adapter supplies `checkId(id): Observable<boolean>` for Verify ID and `inspectId(id): Observable<ReportIdStatus>` for save confirmation (`exists`, optional `name` and `version`). Existing host adapters inherit catalog-based fallbacks. Built-in HTTP adapters use `GET /reports/:id/availability`; the bundled backend returns the name/version in this compact response without fetching report JSON. A 404 falls back to the catalog; older responses without a version require a read of that report. Verification does not select another report or replace the draft. Other failures never mean that an ID is available.
+
+Custom hosts should honor `save(report, { createOnly: true })` for new IDs and `save(report, { expectedVersion })` for confirmed updates. The latter must update only an existing report at that version and reject missing/changed targets atomically. These options are mutually exclusive. Older hosts that ignore them cannot provide concurrency protection. Pending confirmations are invalidated if the ID or endpoint/session context changes.
 
-For applications with custom HTTP pipelines, gRPC, or microservice gateways, extend the library's abstract contracts:
+The designer's `(save)` output is a notification containing the server-confirmed report, including its version. Do not persist it again in the handler:
+
+```html
+<rpt-designer (save)="onReportSaved($event)"></rpt-designer>
+```
 
 ```typescript
-provideBwaysReport({
-  gridComponent: UltraGridComponent,
-  dataSourceAdapter: MyCustomDataSourceAdapter,
-  persistenceAdapter: MyCustomPersistenceAdapter,
-  schemaDiscoveryAdapter: MyCustomSchemaDiscoveryAdapter,
-  lookupAdapter: MyCustomLookupAdapter,
-});
+onReportSaved(report: ReportDefinition): void {
+  this.currentReport = report;
+}
 ```
 
-Abstract base classes:
-- `ReportDataSourceAdapter`
-- `ReportPersistenceAdapter`
-- `ReportSchemaDiscoveryAdapter`
-- `ReportLookupAdapter`
+The built-in backend handles inserts and updates in `CNFREPORTDEF`; no host save handler is needed. For a different backend contract, provide your own `ReportPersistenceAdapter` implementing load, save, list, delete and publish. Its save method must return the persisted report or propagate the failure. Browser storage remains available only through explicit `withLocalStorage()` for offline development.
+
+### Export to `.json` File (Git & Version Control)
+In the designer toolbar, click the **JSON** tab and choose **Download / Export JSON**. This generates a `.json` file that can be committed to Git, reviewed, or imported into staging/production environments.
 
 ---
 
-## 7. Theming & CSS Custom Properties
-
-`bways-report` uses Vanilla CSS custom properties. Customize the tokens in your application's `styles.css`:
-
-```css
-:root {
-  --rpt-color-primary: #2563eb;
-  --rpt-color-primary-hover: #1d4ed8;
-  --rpt-color-bg: #ffffff;
-  --rpt-color-surface: #f8fafc;
-  --rpt-color-text: #0f172a;
-  --rpt-color-text-muted: #64748b;
-  --rpt-color-border: #cbd5e1;
-  --rpt-font-family: 'Inter', system-ui, sans-serif;
-  --rpt-border-radius: 6px;
-  --rpt-border-radius-lg: 8px;
-}
+## 7. Data Grid & UltraGrid Integration
 
-[data-theme='dark'] {
-  --rpt-color-bg: #0f172a;
-  --rpt-color-surface: #1e293b;
-  --rpt-color-text: #f8fafc;
-  --rpt-color-text-muted: #94a3b8;
-  --rpt-color-border: #334155;
-}
-```
+`bways-report` includes a responsive built-in data table. To use the high-performance **UltraGrid** from `bways-grid` (virtual scrolling, Excel-like column filters, column pinning, summary rows):
+
+1. Install `bways-grid`:
+   ```bash
+   npm install bways-grid
+   ```
+2. Pass `UltraGridComponent` to `provideBwaysReport()`:
+   ```typescript
+   import { UltraGridComponent } from 'bways-grid';
+   import { provideBwaysReport } from 'bways-report';
+   import { reportingConfig } from './config';
+
+   provideBwaysReport({
+     ...reportingConfig,
+     grid: UltraGridComponent, // Uses UltraGrid for all reports
+   })
+   ```
 
 ---
 
-## 8. Exporting Data (CSV & JSON)
+## 8. Backend API Contract
 
-Inject `ReportExportService` in any host component:
+The reporting engine communicates with the backend via these REST endpoints:
 
-```typescript
-import { Component, inject } from '@angular/core';
-import { ReportExportService } from 'bways-report';
-
-@Component({ ... })
-export class ExportComponent {
-  private readonly exportService = inject(ReportExportService);
-
-  onExportCsv(data: unknown[]): void {
-    this.exportService.exportCsv(data, {
-      fileName: 'sales-register.csv',
-      columns: [
-        { field: 'invoiceNo', header: 'Invoice #' },
-        { field: 'amount', header: 'Amount' },
-      ],
-      addBom: true, // UTF-8 Excel compatibility
-    });
-  }
-}
-```
+| Endpoint | Method | Purpose | Payload / Response |
+| :--- | :--- | :--- | :--- |
+| `/api/reporting/procedures` | `GET` | Discovers available stored procedures & parameters | Returns `StoredProcedureSummary[]` |
+| `/api/reporting/tables` | `GET` | Discovers database tables, views, and columns | Returns `TableSummary[]` |
+| `/api/reporting/execute` | `POST` | Executes stored procedure or query with form values | Accepts `{ kind, name, parameters }`, returns `Record<string, unknown>[]` |
+| `/api/reporting/reports` | `GET` | Lists all saved report summaries from database | Returns `ReportSummary[]` |
+| `/api/reporting/reports/:id`| `GET` | Fetches single `ReportDefinition` JSON by ID | Returns `ReportDefinition` |
+| `/api/reporting/reports` | `POST`| Inserts/updates `CNFREPORTDEF` | Accepts `{ id, name, definition }` |
+| `/api/reporting/lookup` | `POST` | Fetches dynamic dropdown master data | Accepts `{ table, valueField, displayField }` |
 
 ---
 
 ## License
 
-Proprietary License. Copyright (c) 2026 CCPL / BWays Team. All rights reserved.
+This package is proprietary software. Copyright (c) 2026 CCPL / BWays Team. All rights reserved.
+
+
+## Reliability and security configuration
+
+API data sources forward session credentials, session headers and custom headers only to the application's own origin or an explicitly trusted origin. Public external APIs can still be called without these headers. Cross-origin forwarding requires an exact origin, including the port, configured by the host; report JSON cannot grant this permission. Session secrets interpolated into untrusted URL/body parameters are rejected. Host authentication interceptors must enforce their own matching destination policy.
+
+```typescript
+readonly designerConfig: BwaysReportConfig = {
+  reportsEndpoint: '/api/reporting/reports',
+  executeEndpoint: '/api/reporting/execute',
+  trustedApiOrigins: ['https://trusted-api.example.com:9443'],
+  lookupTimeoutMs: 300000,
+  executionTimeoutMs: 60000,
+};
+```
+
+The same settings can be application defaults in `provideBwaysReport(...)`. Page-local settings remain isolated. Use origins without paths, trailing slashes, embedded credentials or wildcards. `executionTimeoutMs` controls execution requests; when omitted it follows the configured lookup timeout. Client timeouts unsubscribe requests; database command timeouts remain a separate backend setting.
+
+Loading, switching, execution and drill-down cancel superseded requests and reject late results from an earlier session/endpoint context. Closing a drawer or destroying a component cancels its pending work. The report selector exposes loading, empty and retryable error states. Report definitions are checked before rendering; legacy omitted collections are normalized, while malformed structures and unsupported schema versions produce errors.
+
+Viewer preset save/delete operations use `expectedVersion` and update the local report/version only after successful storage. Conflicts retain the current view and show an error. These are report-level shared presets; applications needing private per-user presets should provide separate user-scoped storage rather than embedding them in shared report JSON. Custom persistence adapters must implement atomic version checks.
+
+For table/view execution, the data source can specify a projection, row limit and explicit equality filters:
+
+```typescript
+const dataSource: ReportDataSourceDefinition = {
+  id: 'sales', name: 'Sales', endpoint: 'Sales', type: 'table', schema: 'dbo',
+  columns: ['InvoiceNo', 'Total', 'BranchId'],
+  top: 500,
+  filter: { BranchId: '{{session.branchId}}' },
+};
+```
+
+The adapter sends `columns`, `top` and resolved `filter` values to the execution API. Unmapped form parameters are not automatically treated as SQL column names. The supplied backend defaults table/view results to 1,000 rows and caps requests at 10,000; lookups default to 500. Table/view limits run inside SQL. Stored procedure results are capped in the response; expensive procedures should implement their own SQL-side paging/limits.
+
+Generic backend execution preserves supplied values and leaves omitted procedure arguments for SQL Server to handle. ERP-specific synthetic defaults, flag coercions and legacy fallback behavior require the explicit `legacyErpDefaults` option. See the [backend compatibility settings](../../backend/README.md#query-limits-and-erp-compatibility).