Prototype Library

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.

Inherited reference import '@esa/ecology/esa-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 wrapper exposes --grid-* override hooks, each falling back to a semantic token. Consume these to re-skin AG Grid:

  • Container: --grid-border-color → --color-border, --grid-border-radius → --radius-300, --grid-shadow → --shadow-200, --grid-bg → --color-surface.
  • Type: --grid-font-family → --font-sans, --grid-font-size → --type-size-200.
  • Header: --grid-header-bg → --color-surface-sunken, --grid-header-text → --color-text-secondary, --grid-header-font-size → --type-size-100.
  • Rows: --grid-row-hover-bg → --color-hover-overlay, --grid-row-selected-bg → --color-active-overlay, --grid-row-border-color → --color-border.
  • Cells: --grid-cell-padding-x → --spacing-300, --grid-cell-padding-y → --spacing-200; focus uses --focus-ring-width / --focus-ring-color.