GitHub

Data Grid

esa-grid is a thin Ecology skin over AG Grid (ag-grid-angular / ag-grid-community). It owns the column model, selection, sorting, pagination, quick-filter, and a set of Ecology cell renderers — then themes the underlying AG Grid DOM with design tokens.

Reference wraps AG Grid

Overview

Non-functional reference. This page documents the wrapper around AG Grid (or an equivalent such as TanStack Table) behind the API below. The mock further down is static HTML styled with Ecology tokens — it approximates the rendered grid but does not sort, select, or scroll.

What it wraps

  • Third-party library: AG Grid Community (ag-grid-angular, ag-grid-community).
  • Why a wrapper: AG Grid handles virtual scrolling, column virtualization, sort, filter, and pagination engine. Ecology contributes the column convention (EsaGridColumn), a config object with sane defaults, typed event payloads, themed DOM via ::ng-deep, and five reusable cell renderers.
  • Swappable: the public API (columnDefs, rowData, config, output events) is engine-agnostic enough to re-target TanStack Table if licensing or bundle size demanded it.

API

Inputs

InputTypeDefaultPurpose
columnDefsEsaGridColumn<T>[]requiredColumn definitions (extends AG Grid ColDef with esaRenderer).
rowDataT[]requiredRow data array.
configEsaGridConfig{}High-level options, merged with ESA_GRID_DEFAULTS.
agGridOptionsGridOptions{}Escape hatch for any raw AG Grid option.
quickFilterTextstring''Free-text filter applied across all columns.

Outputs

OutputPayload
rowClicked{ data: T; rowIndex: number }
selectionChanged{ selectedRows: T[]; count: number }
sortChanged{ columnId: string; direction: 'asc' | 'desc' | null }
pageChanged{ page: number; pageSize: number }
gridReadyGridReadyEvent (raw AG Grid api)

Imperative methods: getGridApi(), resizeColumns(), selectAll(), deselectAll().

EsaGridConfig

KeyTypeDefault
paginationbooleanfalse
pageSizenumber100
pageSizeOptionsnumber[][25, 50, 100, 250]
rowSelection'single' | 'multiple' | 'none''none'
showSelectionCheckboxbooleantrue
autoSizeStrategy'fitContents' | 'fitGrid' | 'none''fitContents'
heightstring'calc(100vh - 20rem)'
suppressColumnMenubooleanfalse
quickFilterPlaceholderstring'Search...'
enableTooltipsbooleantrue

Anatomy & static mock

Header row, selection checkbox column, hoverable / selectable body rows, and each of the five Ecology cell renderers in context.

Search… 4 of 128 rows · 1 selected
Site name ↓
Status
Permit #
Reviewed
Actions
Cedar Creek Outfall
Active
WA-0042189
North Fork Lagoon
Pending
WA-0037744
Marsh Restoration B
Wetland Tidal +2 more
WA-0051002
Estuary Monitoring 7
Lapsed
WA-0029810

Cell renderers

Referenced by string via esaRenderer on a column, or by the AG Grid cellRenderer property. Each takes options through cellRendererParams.

Renderer (esaRenderer)Key paramsRenders
esaButton label, icon, variant ('primary'|'secondary'|'outline'|'ghost'), tooltip, disabled, onClick Inline action button.
esaLink routerLinkBase, linkValue, linkDisplay, openInNewTab, externalHref Router or external link, truncated with ellipsis.
esaChips getChips, maxVisible · chip color: default|primary|success|warning|danger Pill chips with optional icon + "+N more" overflow.
esaTooltip tooltipText, copyOnClick, maxWidth Truncated text + native tooltip, optional copy-to-clipboard.
esaCheckbox editable, onToggle Read-only check icon, or an interactive checkbox when editable.

Tokens

The --grid-* hooks are staged: declared in component-tokens.css ahead of the wrapper, so the theming contract is reviewable before code depends on it. Every one falls back to a semantic token. The list below mirrors that file by hand — check it against component-tokens.css when the wrapper lands.

  • Container: --grid-bg → --color-background-elevation-raised, --grid-border-color → --color-border, --grid-radius → --radius-md, --grid-shadow → --elevation-3.
  • Type: --grid-font-family → --typography-font-family-sans, --grid-font-size → --font-size-ui-md.
  • Header: --grid-header-bg, --grid-header-color, --grid-header-weight, --grid-header-font-size → --font-size-ui-sm, --grid-header-border-color.
  • Rows: --grid-row-bg, --grid-row-bg-hover, --grid-row-bg-selected, --grid-row-stripe-bg, --grid-row-border-color, --grid-row-font-size.
  • Cells: --grid-cell-padding-x → --spacing-300, --grid-cell-padding-y → --spacing-200; focus uses --focus-ring-width / --focus-ring-color.
  • Chrome: --grid-toolbar-bg, --grid-toolbar-gap, --grid-toolbar-padding, --grid-pagination-bg, --grid-pagination-border-color.

State goes last, after the property — --grid-row-bg-hover, not --grid-row-hover-bg — matching every other stateful token in the system. Border tokens hold a colour, so a theme can re-point it without restating width and style.