bways-report 0.1.5 → 0.1.7

package/README.md

@@ -1,572 +1,441 @@
 # BWays-Report — Integration & Developer Guide
 
-`bways-report` is an enterprise-grade, metadata-driven reporting platform and visual dynamic page builder for Angular 18+ business & ERP applications.
+`bways-report` is an enterprise reporting platform and visual drag-and-drop page builder for Angular 18+ business & ERP applications with NestJS / SQL Server.
 
-It allows non-developers to visually design reporting pages with filters, KPI metric cards, charts, and grids. The report configuration is saved purely as JSON metadata (`ReportDefinition`), and the runtime engine dynamically instantiates the reactive forms, controls, data queries, and results grid on the fly.
+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.
 
 ---
 [![npm version](https://img.shields.io/npm/v/bways-report.svg)](https://www.npmjs.com/package/bways-report)
-[![license](https://img.shields.io/npm/l/bways-report.svg)](https://github.com/ccplProject/BWays-CustomeReport)
+[![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)
+---
+
+## What's New in v0.2.0
+
+- **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.
+
 ---
 
 ## Table of Contents
 
-1. [Automated Setup (ng add)](#1-automated-setup-ng-add)
-2. [Quick Start (Rule of 1)](#2-quick-start-rule-of-1)
-   - [A. 1-Line App Setup](#a-1-line-app-setup)
-   - [B. 1-Tag Runtime Page](#b-1-tag-runtime-page)
-   - [C. 1-Tag Visual Report Designer](#c-1-tag-visual-report-designer)
-   - [D. Saved Views & Presets in JSON](#d-saved-views--presets-in-json)
-3. [Configuration Options & Zero-Backend Dev](#3-configuration-options--zero-backend-dev)
-4. [Implementing Host Adapters (Advanced)](#4-implementing-host-adapters)
-   - [A. Data Source Adapter (Query Execution)](#a-data-source-adapter)
-   - [B. Persistence Adapter (Saving & Loading Reports)](#b-persistence-adapter)
-   - [C. Master Data Provider (Dropdown Lookups)](#c-master-data-provider)
-5. [Routing & ERP Navigation Integration](#5-routing--erp-navigation-integration)
-6. [Drill-Down Drill-Through & Slide-Over Drawers](#6-drill-down--slide-over-drawers)
-7. [Starter Blueprints Gallery & Branded Exports](#7-starter-blueprints--branded-exports)
+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. Automated Setup (ng add)
+## 1. Quick Start (5 Steps)
 
-Run the Angular CLI schematic to configure your application in seconds:
+### Step 1: Install
 
 ```bash
-ng add bways-report
+npm install bways-report bways-grid @angular/cdk
 ```
 
-This automatically installs required dependencies and adds `provideReporting()` to your `src/app/app.config.ts`.
+> **Compatibility**: Angular 18+ or 19+ standalone architecture with Zone.js or Zoneless change detection.
 
 ---
 
-## 2. Quick Start (Rule of 1)
-
-### A. 1-Line App Setup
+### Step 2: Configure Once (`app.config.ts`)
 
-In your Angular 18+ application:
+Configure `provideBwaysReport()` with a single `BwaysReportConfig` object:
 
 ```typescript
 // src/app/app.config.ts
-import { ApplicationConfig } from '@angular/core';
-import { provideReporting } from 'bways-report';
+import { ApplicationConfig, provideZoneChangeDetection } 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: [
-    // 1-line setup: automatically hooks up HTTP adapters, UltraGridComponent, and session headers
-    provideReporting({ apiBaseUrl: '/api/reporting' }),
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideHttpClient(),
+    provideRouter(routes),
+    provideBwaysReport(reportConfig),
   ],
 };
 ```
 
-> **Zero-Backend / Local Storage Mode:**
-> For local prototyping, offline demos, or frontend-only dev, use:
-> ```typescript
-> provideReporting(withLocalStorage()); // seeds built-in blueprints and saves to browser localStorage
-> ```
-
 ---
 
-### B. 1-Tag Runtime Page
+### Step 3: Drop-in Builder Component
+
+Embed the full visual drag-and-drop report designer with one HTML tag:
 
-Render any saved report with its dynamic filter form, auto-bound stored procedure results, top toolbar, export actions, and saved view presets:
+```html
+<!-- src/app/pages/admin-reports/admin-reports.component.html -->
+<bways-report-builder
+  width="100%"
+  height="calc(100vh - 64px)"
+  (saved)="onReportSaved($event)"
+/>
+```
 
 ```typescript
+// src/app/pages/admin-reports/admin-reports.component.ts
 import { Component } from '@angular/core';
-import { RptReportComponent } from 'bways-report';
+import { BwaysReportBuilderComponent, ReportDefinition } from 'bways-report';
 
 @Component({
   standalone: true,
-  imports: [RptReportComponent],
-  template: `
-    <!-- 1 tag to run and render the full report page -->
-    <rpt-report [id]="'sales-ledger'" />
-  `,
+  imports: [BwaysReportBuilderComponent],
+  templateUrl: './admin-reports.component.html',
 })
-export class SalesReportPage {}
+export class AdminReportsComponent {
+  onReportSaved(report: ReportDefinition): void {
+    console.log('Report saved and published:', report.name, report.slug);
+  }
+}
 ```
 
 ---
 
-### C. 1-Tag Visual Report Designer
+### Step 4: Host Navigation Menu
 
-Embed the full drag-and-drop report builder into your ERP settings or admin portal:
+Display published reports in your host ERP navigation bar or sidebar:
 
+#### Option A: Drop-in Component
+```html
+<!-- Sidebar variant with search filter and category folding -->
+<bways-report-menu variant="sidebar" />
+
+<!-- Or dropdown variant for top navigation bars -->
+<bways-report-menu variant="dropdown" />
+```
+
+#### Option B: Reactive Signal (`injectReportMenu`)
 ```typescript
 import { Component } from '@angular/core';
-import { RptReportDesignerComponent } from 'bways-report';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { injectReportMenu } from 'bways-report';
 
 @Component({
   standalone: true,
-  imports: [RptReportDesignerComponent],
+  imports: [RouterLink, RouterLinkActive],
   template: `
-    <!-- 1 tag to build, preview, or modify any report -->
-    <rpt-report-designer 
-      [id]="'sales-ledger'" 
-      (saved)="onReportSaved($event)" 
-    />
+    <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>
   `,
 })
-export class ReportBuilderPage {
-  onReportSaved(definition: any) {
-    console.log('Report saved successfully:', definition);
-  }
+export class NavigationSidebarComponent {
+  readonly menu = injectReportMenu();
 }
 ```
 
 ---
 
-### D. Saved Views & Presets in JSON
+### Step 5: Declarative Routes (`app.routes.ts`)
 
-When users filter, reorder, group, or format columns in the grid, they can click **"+ Save View"** to persist their customized view preset. Presets are saved directly into the report's JSON:
-
-```json
-{
-  "grid": {
-    "dataSourceId": "ds-sales",
-    "columns": [...],
-    "options": {
-      "presets": [
-        {
-          "id": "preset_1728200000",
-          "name": "Q3 High Value Clients",
-          "gridState": {
-            "filters": { "amount": { "operator": "gte", "value": 50000 } },
-            "columnOrder": ["invoiceId", "amount", "customerName"]
-          }
-        }
-      ]
-    }
-  }
-}
-```
-Users can switch between views seamlessly from the top dropdown, keeping all formatting and custom filters intact.
-
----
-
-### Backend Integration: Mounting `BwaysReportingModule` in NestJS
-
-To power the built-in HTTP adapters, mount `BwaysReportingModule` directly inside your existing NestJS host application:
+Add one line to your route definitions to enable dynamic live report pages:
 
 ```typescript
-// app.module.ts (in your NestJS backend)
-import { Module } from '@nestjs/common';
-import { BwaysReportingModule } from '@bways/reporting-backend';
-
-@Module({
-  imports: [
-    BwaysReportingModule.forRoot({
-      security: {
-        allowedSchemas: ['dbo', 'reporting'],
-        disallowRawSql: true,                    // SQL injection prevention
-        validateEntitiesAgainstCatalog: true,    // Checks sys.procedures catalog
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-### Option B: Custom Adapters (Full Manual Control)
+// src/app/app.routes.ts
+import { Routes } from '@angular/router';
+import { bwaysReportRoutes } from 'bways-report';
+import { AdminReportsComponent } from './pages/admin-reports/admin-reports.component';
 
-If you don't use the standard backend endpoints, you can implement your own adapters:
+export const routes: Routes = [
+  // Admin visual designer route
+  { path: 'admin/reports', component: AdminReportsComponent },
 
-```typescript
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideZoneChangeDetection({ eventCoalescing: true }),
-    provideRouter(routes),
-    provideBwaysReport({
-      gridComponent: BWaysGridComponent,
-      dataSourceAdapter: MyCustomDataSourceAdapter,
-      persistenceAdapter: MyCustomPersistenceAdapter,
-      masterDataProvider: MyCustomMasterDataProvider,
-      defaultPageSize: 25,
-      enableDesigner: true,
+  // 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
     }),
-  ],
-};
+  },
+];
 ```
 
+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!
+
 ---
 
-## 3. Implementing Host Adapters
+## 2. Visual Designer Features
 
-The library is decoupled from your backend. You provide your business application's API handlers by extending three abstract contracts:
+### 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)`
 
-### A. Data Source Adapter
+### 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.
 
-Responsible for executing report queries and returning tabular result rows:
+### 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.
 
-```typescript
-// src/app/services/erp-datasource.adapter.ts
-import { Injectable, inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { Observable } from 'rxjs';
-import { ReportDataSourceAdapter, ReportDataSourceDefinition } from 'bways-report';
-
-@Injectable({ providedIn: 'root' })
-export class ErpDataSourceAdapter extends ReportDataSourceAdapter {
-  private readonly http = inject(HttpClient);
-
-  execute(
-    dataSource: ReportDataSourceDefinition,
-    parameters: Record<string, unknown>
-  ): Observable<unknown[]> {
-    // Send report filter parameters to your backend API endpoint
-    return this.http.post<unknown[]>(dataSource.endpoint, parameters);
-  }
-}
-```
-
-### B. Persistence Adapter
+### 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.
 
-Responsible for saving, loading, listing, and publishing report metadata definitions (`ReportDefinition`):
+### 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.
 
-```typescript
-// src/app/services/erp-persistence.adapter.ts
-import { Injectable, inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { Observable } from 'rxjs';
-import {
-  ReportPersistenceAdapter,
-  ReportDefinition,
-  ReportSummary,
-} from 'bways-report';
-
-@Injectable({ providedIn: 'root' })
-export class ErpPersistenceAdapter extends ReportPersistenceAdapter {
-  private readonly http = inject(HttpClient);
-  private readonly baseUrl = '/api/reports';
-
-  load(reportId: string): Observable<ReportDefinition> {
-    return this.http.get<ReportDefinition>(`${this.baseUrl}/${reportId}`);
-  }
+---
 
-  save(report: ReportDefinition): Observable<ReportDefinition> {
-    return this.http.post<ReportDefinition>(this.baseUrl, report);
-  }
+## 3. Backend Contract Reference
 
-  list(): Observable<ReportSummary[]> {
-    return this.http.get<ReportSummary[]>(this.baseUrl);
-  }
+| 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` |
 
-  delete(reportId: string): Observable<void> {
-    return this.http.delete<void>(`${this.baseUrl}/${reportId}`);
+### Stored Procedure Discovery Format
+```json
+[
+  {
+    "name": "usp_GetCustomerList",
+    "schema": "dbo",
+    "parameters": [
+      { "name": "@BranchId", "sqlType": "int", "required": true },
+      { "name": "@SearchTerm", "sqlType": "varchar", "required": false, "defaultValue": "" }
+    ]
   }
+]
+```
 
-  publish(reportId: string, version: number): Observable<void> {
-    return this.http.post<void>(`${this.baseUrl}/${reportId}/publish`, { version });
+### Table Discovery Format
+```json
+[
+  {
+    "name": "Customers",
+    "schema": "dbo",
+    "type": "table",
+    "columns": [
+      { "name": "CustomerId", "sqlType": "int" },
+      { "name": "CustomerName", "sqlType": "nvarchar" }
+    ]
   }
-}
+]
 ```
 
-### C. Master Data Provider
+### Execution Request Format
+Supports both simplified and enterprise DTO contracts out-of-the-box:
 
-Supplies option lists for dropdowns and lookups (e.g., Customers, Warehouses, Statuses):
-
-```typescript
-// src/app/services/erp-masterdata.provider.ts
-import { Injectable, inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { Observable } from 'rxjs';
-import { MasterDataProvider, DropdownOption } from 'bways-report';
-
-@Injectable({ providedIn: 'root' })
-export class ErpMasterDataProvider extends MasterDataProvider {
-  private readonly http = inject(HttpClient);
-
-  getOptions(
-    masterName: string,
-    filter?: Record<string, unknown>
-  ): Observable<DropdownOption[]> {
-    return this.http.get<DropdownOption[]>(`/api/master-data/${masterName}`, {
-      params: filter as any,
-    });
+**Option A (Simplified contract):**
+```json
+{
+  "kind": "procedure",
+  "name": "usp_GetCustomerList",
+  "schema": "dbo",
+  "parameters": {
+    "BranchId": 1,
+    "SearchTerm": "Acme"
   }
 }
 ```
 
----
-
-## 4. Routing & ERP Navigation Integration
-
-### Dynamic Route Generation
-
-Mount all report runtime and designer routes with a single call in your `app.routes.ts`:
-
-```typescript
-// src/app/app.routes.ts
-import { Routes } from '@angular/router';
-import { createReportRoutes } from 'bways-report';
-
-export const routes: Routes = [
-  {
-    path: 'reports',
-    children: createReportRoutes({
-      // Optional: enforce auth or role guards
-      runtimeGuards: [],
-      designerGuards: [], // e.g. [AdminGuard]
-      enableDesignerRoutes: true, // creates 'new' and ':reportId/edit' routes
-    }),
+**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
+  }
+}
 ```
 
-This instantly creates:
-- `/reports/:reportId` — Renders `RoutedReportRuntimeComponent` (resolves report via `reportResolver`, presents interactive filters, KPI metrics, chart, and result grid).
-- `/reports/:reportId/edit` — Renders `RoutedReportDesignerComponent` (visual drag-and-drop builder loaded with current definition).
-- `/reports/new` — Renders `RoutedReportDesignerComponent` initialized with a blank template.
-
-### Categorized ERP Sidebar / Header Navigation
-
-Use `ReportMenuService` to generate hierarchical sidebar menus grouped by category (e.g. Finance, Sales, Inventory):
-
-```typescript
-// src/app/components/sidebar/erp-sidebar.component.ts
-import { Component, inject } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { RouterModule } from '@angular/router';
-import { ReportMenuService } from 'bways-report';
-
-@Component({
-  selector: 'erp-sidebar',
-  standalone: true,
-  imports: [CommonModule, RouterModule],
-  template: `
-    <aside class="sidebar">
-      <input
-        type="search"
-        placeholder="Search reports..."
-        (input)="onSearch($event)"
-      />
-
-      @for (group of menuService.menuGroups(); track group.category) {
-        <div class="menu-group">
-          <h4>{{ group.displayName }}</h4>
-          <ul>
-            @for (item of group.items; track item.id) {
-              <li>
-                <a [routerLink]="item.route" routerLinkActive="active">
-                  {{ item.name }}
-                  @if (item.isDraft) {
-                    <span class="badge">Draft</span>
-                  }
-                </a>
-              </li>
-            }
-          </ul>
-        </div>
-      }
-    </aside>
-  `,
-})
-export class ErpSidebarComponent {
-  readonly menuService = inject(ReportMenuService);
-
-  onSearch(event: Event): void {
-    const query = (event.target as HTMLInputElement).value;
-    this.menuService.setSearchQuery(query);
-  }
+### 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": {}
 }
 ```
 
 ---
 
-## 5. Embedding Components Directly
-
-If you prefer embedding components inside existing pages instead of routing:
-
-### Report Runtime (Interactive Report Page)
-
-```typescript
-import { Component } from '@angular/core';
-import { ReportRuntimeComponent, ReportDefinition } from 'bways-report';
-
-@Component({
-  selector: 'my-report-page',
-  standalone: true,
-  imports: [ReportRuntimeComponent],
-  template: `
-    <!-- Option A: Load by ID via persistence adapter -->
-    <rpt-runtime [reportId]="'sales-register-2024'" />
+## 4. Dynamic Session Context & Auto-Parameter Binding
 
-    <!-- Option B: Pass ReportDefinition directly -->
-    <!-- <rpt-runtime [report]="customDefinition" /> -->
-  `,
-})
-export class MyReportPageComponent {}
-```
+When `autoParameter: true` is configured, parameters matching active ERP session keys are automatically populated and hidden from non-technical users:
 
-### Visual Drag-and-Drop Designer
+| 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` |
 
+Session values can be updated at runtime:
 ```typescript
-import { Component } from '@angular/core';
-import { DesignerComponent, ReportDefinition } from 'bways-report';
+import { inject } from '@angular/core';
+import { ReportSessionContextService } from 'bways-report';
 
-@Component({
-  selector: 'my-designer-page',
-  standalone: true,
-  imports: [DesignerComponent],
-  template: `
-    <rpt-designer
-      [initialReport]="reportDefinition"
-      (save)="onSaveReport($event)"
-    />
-  `,
-})
-export class MyDesignerPageComponent {
-  reportDefinition: ReportDefinition = /* ... */;
+export class SessionWidget {
+  private readonly session = inject(ReportSessionContextService);
 
-  onSaveReport(updatedReport: ReportDefinition): void {
-    console.log('Saved report schema:', updatedReport);
+  onBranchSwitch(branchId: number): void {
+    this.session.setSessionParameter('branchId', branchId);
   }
 }
 ```
 
 ---
 
-## 6. Grid & Chart Bridge Integration (BWays-Grid)
+## 5. Plugging in BWays-Grid (`UltraGridComponent`)
 
-### Using BWays-Grid or Custom Grid
+`BWays-Report` provides first-class support for `bways-grid` (`v0.1.18+` / `v0.1.19+`). Pass `grid: UltraGridComponent` to `provideBwaysReport()`:
 
-Provide your grid component via the `GRID_COMPONENT` token in `provideBwaysReport()`:
-
-```typescript
-provideBwaysReport({
-  gridComponent: BWaysGridComponent, // or AgGridWrapperComponent
-})
-```
+- **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.
 
-`ReportGridBridgeComponent` dynamically passes the data rows, columns configuration, sorting, and aggregate settings directly to your grid component. If no grid is provided, `bways-report` renders its high-performance built-in tabular grid with pagination and column sorting.
+---
 
-### Using Chart Components
+## 6. Advanced Custom Adapters
 
-Provide a chart component wrapper (Chart.js, ApexCharts, Highcharts) via `chartComponent`:
+For applications with custom HTTP pipelines, gRPC, or microservice gateways, extend the library's abstract contracts:
 
 ```typescript
 provideBwaysReport({
-  chartComponent: MyHostChartComponent,
-})
+  gridComponent: UltraGridComponent,
+  dataSourceAdapter: MyCustomDataSourceAdapter,
+  persistenceAdapter: MyCustomPersistenceAdapter,
+  schemaDiscoveryAdapter: MyCustomSchemaDiscoveryAdapter,
+  lookupAdapter: MyCustomLookupAdapter,
+});
 ```
 
-If not provided, the built-in SVG visual chart renderer outputs crisp, responsive Bar charts, Donut charts, and Line/Area charts with zero external dependencies.
+Abstract base classes:
+- `ReportDataSourceAdapter`
+- `ReportPersistenceAdapter`
+- `ReportSchemaDiscoveryAdapter`
+- `ReportLookupAdapter`
 
 ---
 
 ## 7. Theming & CSS Custom Properties
 
-`bways-report` uses CSS custom properties (`--rpt-*`) throughout all components, ensuring seamless alignment with your ERP application's design system:
+`bways-report` uses Vanilla CSS custom properties. Customize the tokens in your application's `styles.css`:
 
 ```css
-/* In your host application's styles.scss or theme file */
 :root {
-  /* Brand Colors */
-  --rpt-primary: #2563eb;
-  --rpt-primary-hover: #1d4ed8;
-  --rpt-primary-focus: rgba(37, 99, 235, 0.25);
-
-  /* Surface & Text */
-  --rpt-surface-bg: #ffffff;
-  --rpt-bg-subtle: #f8fafc;
-  --rpt-text-color: #0f172a;
-  --rpt-text-muted: #64748b;
-  --rpt-border-color: #e2e8f0;
-
-  /* Geometry & Typography */
-  --rpt-radius-md: 6px;
-  --rpt-radius-lg: 12px;
+  --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-font-size-base: 0.875rem;
-
-  /* Status Colors */
-  --rpt-success-color: #10b981;
-  --rpt-warning-color: #f59e0b;
-  --rpt-error-color: #ef4444;
+  --rpt-border-radius: 6px;
+  --rpt-border-radius-lg: 8px;
 }
-```
-
----
-
-## 8. Registering Custom Host Controls
-
-You can register custom Angular components (e.g., custom slider, multi-select, rich customer picker) into the `ComponentRegistry` so they appear in the Visual Designer palette and render dynamically at runtime:
 
-```typescript
-import { ComponentRegistry, ComponentMetadata } from 'bways-report';
-import { MyCustomPickerComponent } from './my-custom-picker.component';
-
-export function configureCustomControls(registry: ComponentRegistry): void {
-  registry.register({
-    type: 'customer-picker',
-    displayName: 'Customer Picker',
-    category: 'input',
-    icon: 'person_search',
-    component: MyCustomPickerComponent,
-    createDefaultConfig: () => ({
-      id: 'cust-picker',
-      type: 'customer-picker',
-      label: 'Select Customer',
-      properties: { placeholder: 'Search customer...' },
-      layout: { columnSpan: 4 },
-    }),
-    propertySchema: [
-      { key: 'label', label: 'Label', type: 'string', required: true, group: 'General' },
-      { key: 'key', label: 'Field Name (Key)', type: 'string', required: true, group: 'General' },
-      { key: 'required', label: 'Required', type: 'boolean', group: 'Validation' },
-    ],
-  });
+[data-theme='dark'] {
+  --rpt-color-bg: #0f172a;
+  --rpt-color-surface: #1e293b;
+  --rpt-color-text: #f8fafc;
+  --rpt-color-text-muted: #94a3b8;
+  --rpt-color-border: #334155;
 }
 ```
 
 ---
 
-## 9. Exporting Data (CSV & JSON)
+## 8. Exporting Data (CSV & JSON)
 
-Use `ReportExportService` for one-click file generation:
+Inject `ReportExportService` in any host component:
 
 ```typescript
 import { Component, inject } from '@angular/core';
 import { ReportExportService } from 'bways-report';
 
-@Component({
-  selector: 'export-actions',
-  standalone: true,
-  template: `
-    <button (click)="downloadCsv()">Download CSV</button>
-    <button (click)="downloadJson()">Download Metadata</button>
-  `,
-})
-export class ExportActionsComponent {
+@Component({ ... })
+export class ExportComponent {
   private readonly exportService = inject(ReportExportService);
 
-  downloadCsv(): void {
-    const data = [
-      { invoiceNo: 'INV-001', customer: 'Acme Corp', total: 4950 },
-      { invoiceNo: 'INV-002', customer: 'Globex Inc', total: 14080 },
-    ];
-
+  onExportCsv(data: unknown[]): void {
     this.exportService.exportCsv(data, {
-      fileName: 'invoices-export.csv',
+      fileName: 'sales-register.csv',
       columns: [
         { field: 'invoiceNo', header: 'Invoice #' },
-        { field: 'customer', header: 'Customer' },
-        {
-          field: 'total',
-          header: 'Total ($)',
-          formatter: (val: number) => `$${val.toLocaleString()}`
-        },
+        { field: 'amount', header: 'Amount' },
       ],
-      addBom: true, // Includes UTF-8 BOM so Microsoft Excel renders international characters properly
-    });
-  }
-
-  downloadJson(): void {
-    this.exportService.exportJson(myReportDefinition, {
-      fileName: 'report-schema.json',
-      pretty: true,
+      addBom: true, // UTF-8 Excel compatibility
     });
   }
 }
@@ -576,4 +445,4 @@ export class ExportActionsComponent {
 
 ## License
 
-MIT © BWays Technologies
+Proprietary License. Copyright (c) 2026 CCPL / BWays Team. All rights reserved.