Supported host API

This page summarizes the stable consumer surface of @gerald-neumann/gn-vtable 1.4.x. Import these APIs from the package root:

import {
  GnVTableComponent,
  VTableColumnDirective,
  type VTableDataProvider,
} from '@gerald-neumann/gn-vtable';

Components and directives

• <gn-vtable> / GnVTableComponent is the table host.
• <vtable-column> / VTableColumnDirective declares projected columns.
• <vtable-outline-prefix> renders supported outline/WBS prefix chrome.

Key table bindings

Controlled state (models — source of truth)

Model change outputs use the Angular nameChange convention and emit the model value (not a wrapped { name: value } object). Prefer two-way bindings.

(selectionChange) remains for the rich { selectedRows, selectedRowIds } payload. Group delta outputs groupCriteriaAdd / Remove / Reorder remain for analytics.

Other supported inputs

• Data and loading: dataProvider, columns, chunkSize, preFetchChunks, maxCachedChunks, initialLoadStrategy, reloadMode
• Search/sort chrome: enableSearch, initialSearchTerm, initialSortColumns, enableSorting, enableColumnFilters, getColumnFilterValues
• Layout: prefer layoutPreset (default | stretch-fill | overview-card). When preset is default, use fillMode, fillAvailableWidth, layoutMode, tableMinWidth, emptyDisplayMode. Non-default presets override the related fill/layout/min-width inputs.
• Columns: columnGroups, responsiveMode, density, cellLayout, rowHeight
• Grouping/outline: groupingStrategy, showGroupRail, pivotSchema, outlineMode, outlineParentField, outlineColumn
• Selection/editing: selectionMode, selectionUi, rowIdField, inlineEditActivation
• Host chrome: customTranslations, iconLibrary, iconLibraries, performanceLogger, action/toolbar/empty-state templates

Store-construction-only inputs (chunkSize, preFetchChunks, maxCachedChunks, initialLoadStrategy, performanceLogger, maxConcurrentChunkFetches) are read once when the internal store is created; changing them later is ignored (dev builds warn).

Other outputs

rowClick, actionClick, cellEditCommit, cellEditCancel, outlineToggle, dragStart, dragEnd, drop.

Supported imperative methods (frozen)

Companion panes may use visibleRows, companionLayout, companionVisibleRange, companionScrollTop, companionHeaderBandHeight, effectiveRowHeight, plus status signals loading, error, filteredRecords, totalRecords, and loadedRecords.

protected members are template-only and are not a supported host API.

Provider contract

Every VTableDataProvider<T> implements:

• fetchData(params) → Observable<VTableResponse<T>>
• fetchDataCount(params) → Observable<number>

Grouped loading additionally uses both optional hooks:

• fetchGroups(params)
• fetchGroupRows(params)

fetchChildren is deprecated and is not called by the table. Handle (outlineToggle) in the host instead.

CI includes provider-conformance.spec.ts for minimal flat / group-first shapes.

Absolute minimum (hardcoded rows)

Runnable: .\start-minimum-sample.ps1 → http://localhost:4210 (projects/minimum-sample).

import { Component } from '@angular/core';
import { of } from 'rxjs';
import {
  GnVTableComponent,
  VTableColumnDirective,
  type VTableDataProvider,
} from '@gerald-neumann/gn-vtable';

type Person = { name: string; city: string };

const rows: Person[] = [
  { name: 'Ada Lovelace', city: 'London' },
  { name: 'Alan Turing', city: 'Manchester' },
  { name: 'Grace Hopper', city: 'New York' },
];

function filterRows(search?: string): Person[] {
  const q = search?.trim().toLowerCase();
  if (!q) return rows;
  return rows.filter(
    (r) => r.name.toLowerCase().includes(q) || r.city.toLowerCase().includes(q),
  );
}

@Component({
  imports: [GnVTableComponent, VTableColumnDirective],
  template: `
    <gn-vtable [dataProvider]="provider" [chunkSize]="50">
      <vtable-column field="name" title="Name" />
      <vtable-column field="city" title="City" />
    </gn-vtable>
  `,
})
export class MinimalTablePage {
  readonly provider: VTableDataProvider<Person> = {
    fetchDataCount: ({ search }) => of(filterRows(search).length),
    fetchData: ({ start, length, search }) => {
      const filtered = filterRows(search);
      return of({
        data: filtered.slice(start, start + length),
        recordsTotal: rows.length,
        recordsFiltered: filtered.length,
      });
    },
  };
}

Search is applied client-side above. Sort / column filters are still ignored — map sortColumns / columnFilters the same way (or swap the array for an HTTP provider).

Export tiers

Migration cheat sheet: MIGRATION-ADVANCED-EXPORTS.md.