@firestitch/grid

A virtual-scrolling grid for Angular 18 that shows either a pivot (row levels, column levels and values) or a source's own lines (details), with sorts and filters on every column header, expandable groups, total rows and columns, and a layout panel docked beside it. The grid never holds a dataset: it asks a GridSource for the rows on screen and reads more as the viewer scrolls and opens groups.

Install

npm install @firestitch/grid

Like every Firestitch package, the grid declares no peer dependencies. The app installs the packages the grid imports itself:

An app must install every one of them, @firestitch/datepicker, @firestitch/form and @firestitch/popover included: the app does not build without them, and @firestitch/popover must be 18.1.0 or later. @firestitch/datepicker and @firestitch/form import @firestitch/clear, common, date, dialog, drawer, message and scroll-picker, and @firestitch/drawer needs @firestitch/core and @firestitch/store. An app that already uses fs-datepicker has them.

Usage

fs-grid is a standalone component.

import { HttpClient } from '@angular/common/http';
import { Component, inject, signal } from '@angular/core';

import {
  FsGridComponent,
  GridAggregation,
  GridGranularity,
  GridLayout,
  GridResult,
  GridSource,
} from '@firestitch/grid';

@Component({
  selector: 'app-sales-grid',
  standalone: true,
  imports: [FsGridComponent],
  template: '<fs-grid [source]="source" [(layout)]="layout"></fs-grid>',
})
export class SalesGridComponent {
  public layout = signal<GridLayout>({
    rows: [{ field: 'region' }],
    columns: [{ field: 'orderedOn', granularity: GridGranularity.Month }],
    values: [{ field: 'revenue', aggregation: GridAggregation.Sum }],
    totalRow: true,
  });

  public source: GridSource = {
    read: (request, params) => this._http.post<GridResult>('/sales/grid', { request, params }),
  };

  private _http = inject(HttpClient);
}

Inputs

The source

export interface GridSource {
  read(request: GridRequest, params: GridParams): Observable<GridResult>;
}

• Each emit is a part of the answer, and complete means done.
• The read is cold, and unsubscribing aborts it. The grid cancels reads it no longer needs.
• request.rows names the row ranges wanted, request.columns the column range, and request.fields asks for the source's fields and limits too.
• An error arrives as an Error with a readable message; the grid shows it with a Retry.

Layout helpers

• canonicalGridLayout(layout) gives the layout as a host stores and compares it: defaults are left out and keys come in one order, so two layouts that mean the same have the same JSON.
• normalizeGridLayout(layout) is the forgiving read: unknown keys and entries without a field are dropped, and every list and flag comes back present.

Styles

The grid paints from its own component styles, the --fs-* tokens of @firestitch/style and the Angular Material theme. There is nothing to include: the package's styles.scss is empty and ships only so the build lays out like the other Firestitch packages.

Development

npm run serve     # the playground, with every example
npm run check     # the engine, contract and client checks
npm run package   # the checks, then package/ with this README and the LICENSE

License

MIT. See LICENSE.