data-grid-angular

An Angular library that provides enterprise data grids for Nawras / Saned applications — with server-side paging, client-side get-all grids, column menus, filtering, sorting, Excel/CSV export, lookup columns, pinned total rows, and an AG Grid–compatible facade API.

It gives you:

• Server-side grid — <app-custom-ag-grid> / <nawras-enterprise-grid> with Saned API paging, block cache, and skeleton loading
• Client-side get-all grid — <app-custom-ag-grid-get-all> for full in-memory datasets with pagination, row grouping, and export
• Pinned total row grid — <app-custom-ag-grid-total-row> for summary/footer rows on paged data
• Lookup dropdown — <app-lookup-select> for server-driven PrimeNG dropdowns wired to Saned lookup APIs
• Column definition model — GridColumnDef with support for grouped headers, cell renderers, editable cells, and lookup filters
• Saned API helpers — query/filter types, DTO mapping, locale merge, and AG Grid locale text via @ngx-translate/core
• Grid facade API — NawrasGridFacadeApi with AG Grid–compatible methods (setRowData, applyTransaction, exportDataAsExcel, …)

Contents

• What this library does
• When to use it
• Package contents
• Requirements / peer dependencies
• Installation
• Quick start
  • Server-side grid (Saned API)
  • Client-side get-all grid
  • Lookup select dropdown
• Components
  • NawrasEnterpriseGridComponent
  • NawrasEnterpriseGridGetAllComponent
  • NawrasEnterpriseGridTotalRowComponent
  • LookupSelectComponent
• Column definitions
• Grid facade API
• Saned API types & utilities
• Total row utilities
• Row grouping (get-all grid)
• Export (CSV / Excel)
• Legacy import names
• Maintainer notes
• License

What this library does

This library replaces legacy AG Grid hosts with a custom Nawras data grid (NawrasDataGridComponent) wrapped by higher-level enterprise components.

It focuses on:

• Saned backend integration — paged getPaged requests, filter/query mapping, block-based remote cache
• Familiar AG Grid ergonomics — column defs, grid options, facade API, context menu export, row transactions
• Production UX — loading skeletons, responsive viewport row counts, RTL support, ngx-translate headers
• Lookup columns — floating filter cells backed by Saned lookup APIs
• Total / summary rows — pin the last row of a page or match a custom predicate to the grid footer

The published npm package is data-grid-angular. Legacy code may still import CustomAgGrid* symbols — they are aliases for the Nawras names (see Legacy import names).

When to use it

Use this library if your Angular app needs:

• A data grid connected to Saned REST APIs with server-side pagination
• A client-side grid that loads all rows once and paginates/filters/sorts locally
• Lookup dropdowns populated from Saned shared-data endpoints
• Excel/CSV export, column reorder/resize/pin, and cell context menus
• Row add/update/delete highlighting after dialog saves

Typical examples:

• HR, payroll, and ERP list screens
• Approval workflows with paged grids
• Reports with grouped rows and export
• Forms that need server-driven lookup fields

Package contents

Everything under src/lib/ ships in the published bundle:

| Folder / area | Purpose | |---|---| | data-grid/ | Core grid engine — virtual scrolling, column layout, filters, sorting, cell editors, pagination, row grouping | | nawras-enterprise-grid/ | High-level grid hosts (server-side, get-all, total row), remote service, facade API, client export | | lookup-select/ | <app-lookup-select> dropdown + lookup column types | | ag-grid-loading-skeleton/ | Loading skeleton overlay while data is fetched | | excel-export/ | Excel export service (column state for server export) | | formatters/ | Date/time cell format renderers | | pipes/ | ApiMergedLocalePipe for bilingual API values | | service/ | ApiBaseService, LookupListService for Saned HTTP calls | | custom-ag-grid-shared.ts | Saned types, filter enums, DTO mapping, AG Grid locale builder |

Public exports are defined in src/public-api.ts.

Requirements / peer dependencies

The consuming application must provide:

| Dependency | Used for | |---|---| | @angular/common ^18.2.0 | Core Angular (declared peer) | | @angular/core ^18.2.0 | Core Angular (declared peer) | | @angular/forms | Lookup select, cell editors | | @angular/common/http | Saned API calls | | @ngx-translate/core | Grid locale text and header translation | | primeng | Dropdown, tooltip, toast (lookup select & grid messages) | | primeicons | Grid UI icons | | rxjs | Observables in remote grid service |

Optional (used by host apps / column renderers, not bundled as hard peers):

• ag-grid-community — type compatibility for legacy column defs and grid options
• exceljs — Excel export in consuming apps

Why peer dependencies? Your application owns framework versions. This prevents duplicate Angular/PrimeNG copies and version conflicts.

Installation

npm i data-grid-angular

Install the peer dependencies above in your app if they are not already present.

Quick start

Server-side grid (Saned API)

1) Import the module in your feature module (do not re-declare the component):

import { NawrasEnterpriseGridModule } from 'data-grid-angular';

@NgModule({
  imports: [NawrasEnterpriseGridModule],
})
export class MyFeatureModule {}

2) Add the grid in your template:

<app-custom-ag-grid
  [apiUrl]="'/api/my-module/MyEntity/v1'"
  [columnDefs]="columnDefs"
  [filters]="parentFilters"
  (filtersChange)="parentFilters = $event"
  (gridReady)="onGridReady($event)"
  (paginationChanged)="onPageChange($event)"
/>

3) Define columns in your component:

import { GridColumnDefInput } from 'data-grid-angular';

columnDefs: GridColumnDefInput[] = [
  { field: 'id', headerName: 'ID', width: 80 },
  { field: 'name', headerName: 'Name', sortable: true, filter: true },
  { field: 'createdDate', headerName: 'Created', sort: 'desc' },
];

4) Use the facade API after gridReady:

onGridReady(event: { api: NawrasGridFacadeApi }) {
  this.gridApi = event.api;
}

refreshGrid() {
  this.gridApi?.refreshServerSide({ purge: true });
}

Client-side get-all grid

For screens that load all rows once (no Saned paging):

<app-custom-ag-grid-get-all
  [columnDefs]="columnDefs"
  [rowData]="allRows"
  [loading]="isLoading"
  (gridReady)="onGridReady($event)"
  (reloadRequested)="loadAllRows()"
/>

Supports client pagination, column filters, sorting, row grouping, clipboard export, and (reloadRequested) after add/update/delete.

Lookup select dropdown

1) Import the module:

import { LookupSelectModule } from 'data-grid-angular';

@NgModule({
  imports: [LookupSelectModule],
})
export class MyFormModule {}

2) Use in a template (works with ngModel or reactive forms via ControlValueAccessor):

<app-lookup-select
  entity="Department"
  module="SanedSharedData"
  version="v1.2"
  placeholder="Select department"
  [(ngModel)]="departmentId"
/>

Components

NawrasEnterpriseGridComponent

| | | |---|---| | Selector | app-custom-ag-grid | | Module | NawrasEnterpriseGridModule / CustomAgGridModule | | Purpose | Server-side (Saned API) or client-side grid with remote block cache |

Key inputs

| Input | Description | |---|---| | apiUrl | Saned entity URL (enables remote paging when set) | | columnDefs | Column definitions | | rowData | Optional client-side row data (when not using apiUrl) | | loading | true = skeleton, false = show data, null = auto | | filters / (filtersChange) | Parent query filters merged with column filters | | searchText | Quick filter / search box text | | newRow / updatedRow / deleteRow | Push row changes after dialog save | | gridOptions | Row model, page size, selection, row height, etc. | | totalRowPredicate | Pin matching row to footer | | pinLastRowOfFullSanedBlock | Auto-pin last row of full API blocks | | highlightChanges | Flash rows after add/update | | rowId | Id field name (default id) | | maxVisibleBodyRows | Viewport row cap before inner scroll | | contextMenuLabels | Override clipboard/export menu labels |

Key outputs

| Output | Description | |---|---| | gridReady | { api: NawrasGridFacadeApi } | | filtersChange | Updated QueryFilters | | paginationChanged | { pageIndex, pageSize, totalItems } | | cellClicked / cellValueChanged | Cell interaction events | | rowChangeApplied | After newRow / updatedRow merged |

NawrasEnterpriseGridGetAllComponent

| | | |---|---| | Selector | app-custom-ag-grid-get-all | | Module | NawrasEnterpriseGridGetAllModule / CustomAgGridGetAllModule | | Purpose | Client-side grid — all rows in memory |

Key inputs: columnDefs, rowData, loading, gridOptions, filters, highlightChanges, rowId, maxVisibleBodyRows, translateHeaders, columnMenuLabels, contextMenuLabels, paginationPageSizeSelector.

Key outputs: gridReady, cellClicked, cellValueChanged, paginationChanged, reloadRequested.

Supports row grouping via gridOptions (groupDisplayType, groupDefaultExpanded) and column defs (rowGroup, showRowGroup).

NawrasEnterpriseGridTotalRowComponent

| | | |---|---| | Selector | app-custom-ag-grid-total-row | | Module | NawrasEnterpriseGridTotalRowModule / CustomAgGridTotalRowModule | | Purpose | Same as server-side grid with pinned total-row styling |

Extends NawrasEnterpriseGridComponent. Use with totalRowPredicate or pinLastRowOfFullSanedBlock.

LookupSelectComponent

| | | |---|---| | Selector | app-lookup-select | | Module | LookupSelectModule | | Purpose | Server-driven PrimeNG dropdown for Saned lookups |

Key inputs: entity, module, version, functionName, getAll, query, placeholder, optionLabel, optionValue, selectFirstOnLoad, searchDebounce, editMode, session.

Implements ControlValueAccessor — bind with ngModel or formControlName.

Column definitions

Columns use GridColumnDef / GridColumnDefInput:

const col: GridColumnDefInput = {
  field: 'statusId',
  headerName: 'Status',
  sortable: true,
  filter: true,
  width: 140,
  pinned: 'left',
  lookup: {
    module: 'SanedSharedData',
    entity: 'Status',
    version: 'v1.2',
    optionLabel: 'text',
    optionValue: 'id',
  },
  cellRenderer: MyStatusComponent,      // standalone Angular component
  cellRendererModule: MyStatusModule,   // optional DI module
  editable: true,
  sort: 'asc',
  sortIndex: 0,
  rowGroup: true,                         // get-all grid grouping
  children: [/* grouped header columns */],
};

Supported capabilities:

• Grouped headers (children)
• Pin left/right, resize, hide, flex width
• Floating lookup filters
• Custom cell renderers (function or Angular component)
• Inline cell editing (text, number, boolean checkbox)
• Initial sort (sort, sortIndex)
• Row group source / display columns

Grid facade API

NawrasGridFacadeApi is exposed on gridReady. It mirrors common AG Grid API methods:

| Method | Description | |---|---| | refreshServerSide({ purge }) | Reload remote data | | setRowData(rows) | Replace all rows (client grid) | | applyTransaction({ add, update, remove }) | Row CRUD without refetch | | applyServerSideTransaction(...) | SSRM-style transaction | | setQuickFilter(text) | Client quick filter | | setFilterModel(model) | Column filter model | | exportDataAsCsv(fileName?) | Export visible data as CSV | | exportDataAsExcel(fileName?) | Export visible data as Excel | | sizeColumnsToFit() | Auto-fit columns | | getSelectedRows() | Current selection | | refreshCells(params) / redrawRows(params) | Re-render cells | | forEachNode(callback) | Iterate displayed rows | | setGridOption(option, value) | Set grid option (AG Grid compat) |

Types: NawrasGridFacadeApi, NawrasGridOptions, NawrasGridRowNode, NawrasServerSideTransaction.

Saned API types & utilities

Exported from custom-ag-grid-shared:

| Export | Description | |---|---| | SanedQuery | Page index, page size, search, filters, orders | | SanedList<T> | { items, pageInfo } list response | | SanedResponse<T> | Standard Saned API envelope | | QueryFilters / FilterValue | Filter model for API queries | | SanedFilterConditionValue | Equal, GreaterThan, IN, NotEqual, … | | SanedOrdersConditionsValue | ASC / DESC | | buildAgGridLocale(translate) | AG Grid locale strings via ngx-translate | | getMappedListData / getMappedSingleData | DTO + lookup + locale mapping | | getMappedApiDto | Merge Ar suffix fields for API POST | | DtoMappingOptions / getOptions | Mapping configuration | | IMapperDtoModel | Custom row mapper interface |

Total row utilities

Exported helpers for pinned footer / summary rows:

import {
  splitTotalRowFromItems,
  findLastPinnedTotalRow,
  stripTotalRowsFromItems,
  isNawrasBodyRowHidden,
  countNawrasVisibleBodyRows,
  NAWRAS_IS_PINNED_TOTAL_ROW,
  NAWRAS_PINNED_TOTAL_ROW_ID,
} from 'data-grid-angular';

Use when building custom data pipelines that need the same total-row semantics as the grid hosts.

Row grouping (get-all grid)

Enable via gridOptions and column defs:

gridOptions = {
  groupDisplayType: 'singleColumn',
  groupDefaultExpanded: 1,
};

columnDefs = [
  { field: 'country', rowGroup: true, hide: true },
  { field: 'city', showRowGroup: 'country' },
  { field: 'amount' },
];

Utilities: normalizeColumnDefsForRowGrouping, countRootGroupRows.

Export (CSV / Excel)

• Context menu — right-click a cell for Copy / CSV / Excel / Excel (merged cells)
• Facade API — gridApi.exportDataAsCsv() / exportDataAsExcel()
• Get-all grid — client-side export via exportNawrasGridToCsv / exportNawrasGridToExcel (internal)

Override menu labels with contextMenuLabels input.

Legacy import names

For backward compatibility, these aliases are exported alongside Nawras names:

| Legacy name | Nawras name | |---|---| | CustomAgGridComponent | NawrasEnterpriseGridComponent | | CustomAgGridModule | NawrasEnterpriseGridModule | | CustomAgGridGetAllComponent | NawrasEnterpriseGridGetAllComponent | | CustomAgGridGetAllModule | NawrasEnterpriseGridGetAllModule | | CustomAgGridTotalRowComponent | NawrasEnterpriseGridTotalRowComponent | | CustomAgGridTotalRowModule | NawrasEnterpriseGridTotalRowModule |

Both naming styles resolve to the same classes.

Maintainer notes

This library was generated with Angular CLI version 18.2.0.

Build

Run from the Angular workspace root (lib/), not from this folder alone:

cd E:\Github\ng-nawras\lib
npm run build

Or from this package directory (delegates to the workspace):

cd lib/projects/data-grid
npm run build

Equivalent Angular CLI command:

ng build data-grid

Build artifacts are stored in lib/dist/data-grid/.

Publish

After building:

cd dist/data-grid
npm publish

Unit tests

ng test data-grid

Runs unit tests via Karma.

Code scaffolding

ng generate component component-name --project data-grid

Use --project data-grid so files are added to this library, not the default app project.

License

MIT (update if your package uses a different license).