AG-Grid Patterns for TMNL

Critical: AG-Grid v34 Module Registration

Without this, grid renders blank. No exceptions.

typescript

import { ModuleRegistry, AllCommunityModule } from 'ag-grid-community'
ModuleRegistry.registerModules([AllCommunityModule])

No CSS imports needed when using the theme prop.

Canonical Sources

Core Library (v2)

Compound component: src/lib/data-grid/components/UnifiedDataGrid.tsx
Context system: src/lib/data-grid/components/DataGridContext.tsx
Theme composer: src/lib/data-grid/composer/theme-composer.ts
Flash system: src/lib/data-grid/flash/index.ts
Cell renderers: src/lib/data-grid/renderers/
Variants: src/lib/data-grid/variants/
Barrel export: src/lib/data-grid/index.ts

tldraw Integration

V2 shape (modern): src/components/tldraw/shapes/data-grid-shape-v2.tsx
V1 shape (legacy): src/components/tldraw/shapes/data-grid-shape.tsx
Hybrid drag: src/components/tldraw/shapes/data-grid-shape.tsx:366-594

Architecture Documentation

Deep dive: assets/documents/AG_GRID_THEMING_ARCHITECTURE.md

Pattern 1: Tmnl.DataGrid — COMPOUND COMPONENT API

When: Building any data grid in TMNL.

The modern API uses compound components for declarative composition.

tsx

import { Tmnl } from '@/lib/data-grid'
import { tmnlDenseDark } from '@/lib/data-grid/variants/tmnl-dense-dark'

<Tmnl.DataGrid
  id="emitters"
  variant={tmnlDenseDark}
  rowData={data}
  columnDefs={columnDefs}
>
  <Tmnl.DataGrid.Header>
    <Tmnl.DataGrid.Title title="EMITTERS" badge={data.length} />
    <Tmnl.DataGrid.SettingsButton onClick={openSettings} />
  </Tmnl.DataGrid.Header>

  <Tmnl.DataGrid.Body />

  <Tmnl.DataGrid.StatusBar>
    <span className="text-cyan-500">V2</span>
    <span>{data.length} rows</span>
  </Tmnl.DataGrid.StatusBar>

  <Tmnl.DataGrid.CornerDecorations />
</Tmnl.DataGrid>

Child Components

Component	Purpose	Props
`Header`	Container for title/controls	children
`Title`	Grid title with optional badge	title, badge?
`SettingsButton`	Settings action button	onClick
`Body`	The actual AG-Grid	(none - uses context)
`StatusBar`	Footer status area	children
`CornerDecorations`	Visual corner accents	variant?

Per-Grid Runtime Isolation

Each <Tmnl.DataGrid> creates its own Effect runtime with isolated services:

typescript

// Inside Tmnl.DataGrid provider
const runtime = useMemo(() => createDataGridRuntime(), [gridId])

// Child components access via context
const ctx = useDataGridContext()
const variant = ctx.variant      // Reactive variant
const gridApi = ctx.gridApi      // Reactive grid API

Canonical source: src/lib/data-grid/components/UnifiedDataGrid.tsx

Pattern 2: GridVariant System — VARIANT-DRIVEN THEMING

When: Customizing grid appearance, density, or behavior.

Variants are not just themes. They encode:

Density — Row height, font size, padding
Colors — Background, text, signals, flash
Behavior — Selection, sorting, drag, resize
Typography — Font family, letter spacing, weight

Variant Structure

typescript

export const tmnlDenseDark: GridVariant = {
  id: 'tmnl-dense-dark',
  densityTier: 'dense',
  density: DENSITY_PRESETS.dense,
  colorScheme: 'dark',

  colors: {
    background: { base: '#000000', alternateRow: '#0a0a0a', header: '#0d0d0d' },
    text: { primary: '#ffffff', secondary: '#a3a3a3', muted: '#525252' },
    signal: { positive: '#22c55e', negative: '#ef4444', accent: '#00ffcc' },
    border: { primary: '#262626', muted: '#1a1a1a' },
    flash: {
      up: 'rgba(34, 197, 94, 0.4)',
      down: 'rgba(239, 68, 68, 0.4)',
      durationMs: 1500,
    },
  },

  behavior: BEHAVIOR_PRESETS.interactive,

  typography: {
    fontFamily: "'JetBrains Mono', monospace",
    headerLetterSpacing: '0.05em',
  },

  intentOverrides: {
    // Per-column styling rules
  },
}

Density Presets

Preset	Row Height	Font Size	Padding
`dense`	20px	10px	4px
`compact`	24px	11px	6px
`normal`	32px	13px	8px
`comfortable`	40px	14px	12px

Behavior Presets

Preset	Selection	Sorting	Drag	Resize
`readonly`	none	true	false	false
`interactive`	single	true	true	true
`editable`	multiple	true	true	true
`minimal`	none	false	false	false

Variant → Theme Conversion

typescript

import { composeAgGridTheme } from '@/lib/data-grid/composer/theme-composer'

const agTheme = composeAgGridTheme(tmnlDenseDark)
// Returns AG-Grid themeQuartz.withParams({...})

Canonical source: src/lib/data-grid/variants/tmnl-dense-dark.ts

Pattern 3: Flash System — CELL CHANGE HIGHLIGHTING

When: Showing real-time data updates with visual feedback.

Severity Mapping

Delta	Severity	Visual Effect
0	none	No flash
1-5	low	Subtle background
6-10	medium	Visible pulse
11-15	high	Strong glow
16+	critical	Full glow + pulse

Flash State Structure

typescript

interface FlashState {
  severity: 'none' | 'low' | 'medium' | 'high' | 'critical'
  intensity: number      // 0-1, logarithmic scale
  direction: 'up' | 'down' | 'neutral'
  delta: number
  timestamp: number
  isActive: boolean
}

useFlashTracker Hook

typescript

import { useFlashTracker } from '@/lib/data-grid/flash'

const { getFlashState, hasFlash, processUpdates, injectKeyframes } = useFlashTracker({
  maxDelta: 20,
  flashExpirationMs: 1500,
})

// Initialize (once)
useEffect(() => injectKeyframes(), [])

// Process row updates
useEffect(() => {
  processUpdates(newData, oldData, 'value')
}, [newData])

// In cell renderer
const flash = getFlashState(rowId, field)
const styles = generateFlashStyles(flash, { colors: variant.colors.flash })

Flash in Cell Renderer

tsx

function ValueCellRenderer(params: ICellRendererParams) {
  const ctx = useDataGridContext()
  const { getFlashState } = ctx.flash

  const flash = getFlashState(params.node.id, params.colDef.field)

  return (
    <div
      className={flash.isActive ? `flash-${flash.severity}` : ''}
      style={{
        backgroundColor: flash.isActive
          ? flash.direction === 'up'
            ? ctx.variant.colors.flash.up
            : ctx.variant.colors.flash.down
          : undefined,
      }}
    >
      {params.value}
    </div>
  )
}

Canonical source: src/lib/data-grid/flash/index.ts

Pattern 4: DataGridContext — PER-GRID SERVICES

When: Child components need access to grid state, variant, or API.

Context Shape

typescript

interface DataGridContextValue<TData = unknown> {
  gridId: string
  runtime: DataGridRuntime           // Per-grid Effect services
  variant: GridVariantType           // Reactive variant
  rowData: TData[]
  columnDefs: ColDef<TData>[]
  getRowId?: GetRowIdFunc<TData>
  gridApi: GridApi | null            // AG-Grid API reference
  setGridApi: (api: GridApi | null) => void
  flash: FlashTrackerAPI
}

Usage in Components

typescript

// Required context (throws if missing)
const ctx = useDataGridContext()

// Optional context (returns null if outside grid)
const ctx = useDataGridContextMaybe()

Color Extraction from Context

typescript

function StatusCellRenderer(params: ICellRendererParams) {
  const ctx = useDataGridContextMaybe()

  // Variant colors with fallback
  const colors = ctx?.variant.colors ?? {
    signal: { positive: '#22c55e', negative: '#ef4444' }
  }

  return (
    <span style={{ color: colors.signal.positive }}>
      {params.value}
    </span>
  )
}

Canonical source: src/lib/data-grid/components/DataGridContext.tsx

Pattern 5: Context-Aware Cell Renderers

When: Renderers need variant colors or grid services.

Pattern: Fallback for Standalone Usage

typescript

import { useDataGridContextMaybe } from '@/lib/data-grid'
import { COLORS } from '@/lib/tokens'

export function ValueCellRenderer(params: ValueCellRendererParams) {
  const ctx = useDataGridContextMaybe()

  // Colors from variant OR token fallback
  const textColor = ctx?.variant.colors.text.primary ?? COLORS.textPrimary
  const accentColor = ctx?.variant.colors.signal.accent ?? COLORS.accentCyan

  return (
    <div style={{ color: textColor }}>
      <span>{params.value}</span>
      <div
        style={{
          backgroundColor: accentColor,
          width: `${params.data.percentage}%`,
        }}
      />
    </div>
  )
}

Pattern: Flash-Aware Renderer

typescript

export function FlashValueRenderer(params: ICellRendererParams) {
  const ctx = useDataGridContext()
  const flash = ctx.flash.getFlashState(params.node.id, params.colDef.field!)

  return (
    <div
      className={cn(
        'transition-all duration-300',
        flash.isActive && `flash-${flash.severity}`,
        flash.direction === 'up' && 'text-green-400',
        flash.direction === 'down' && 'text-red-400',
      )}
    >
      {params.value}
    </div>
  )
}

Canonical source: src/lib/data-grid/renderers/ValueCellRenderer.tsx

Pattern 6: Hybrid Drag System — GRID-TO-CANVAS

When: Dragging rows from AG-Grid onto a tldraw canvas.

Drag Phase Transitions

┌─────────────────────────────────┐
│   AG-Grid Internal Drag         │
│   (rowDragManaged=true)         │
└──────────────┬──────────────────┘
               │ onRowDragMove
               ▼
        Check: outside grid bounds?
               │
        ┌──────┴──────┐
       NO            YES
        │             │
     Continue    Create ghost
     in grid     shape on canvas
        │             │
        │      onPointerMove
        │      updateGhost()
        │             │
        └─────┬───────┘
              │ onPointerUp
        spawnDataCard()
        Remove ghost

Drag State Schema

typescript

interface DragState {
  isDragging: boolean
  isOutsideGrid: boolean    // Key flag for phase transition
  rowData: DataGridRow | null
  ghostId: string | null    // tldraw shape ID
}

Phase Handlers

typescript

const onRowDragMove = useCallback((event: RowDragMoveEvent) => {
  const { clientX, clientY } = event.event
  const gridRect = gridRef.current?.getBoundingClientRect()

  const isOutside = !gridRect ||
    clientX < gridRect.left || clientX > gridRect.right ||
    clientY < gridRect.top || clientY > gridRect.bottom

  if (isOutside && !dragState.isOutsideGrid) {
    // Transition: GridInternal → CanvasTracking
    const ghostId = createGhostShape(dragState.rowData, { x: clientX, y: clientY })
    setDragState(prev => ({ ...prev, isOutsideGrid: true, ghostId }))
  } else if (!isOutside && dragState.isOutsideGrid) {
    // Transition: CanvasTracking → GridInternal
    removeGhostShape(dragState.ghostId)
    setDragState(prev => ({ ...prev, isOutsideGrid: false, ghostId: null }))
  }
}, [dragState, createGhostShape, removeGhostShape])

Effect Service for Drag

typescript

export interface GridDragServiceApi {
  readonly getState: Effect.Effect<DragState>
  readonly dispatch: (event: GridDragEvent) => Effect.Effect<void>
  readonly subscribe: (handler: (state: DragState) => void) => Effect.Effect<() => void>
  readonly isDragging: Effect.Effect<boolean>
  readonly getPhase: Effect.Effect<DragPhase>
}

Canonical source: src/lib/data-grid/services/GridDragService.ts

Pattern 7: Theme Composition via composeAgGridTheme

When: Converting a GridVariant to an AG-Grid theme.

typescript

import { themeQuartz } from 'ag-grid-community'

export function composeAgGridTheme(variant: GridVariant) {
  const { colors, density, typography } = variant

  return themeQuartz.withParams({
    // Core colors
    backgroundColor: colors.background.base,
    foregroundColor: colors.text.primary,
    accentColor: colors.signal.accent,

    // Header
    headerBackgroundColor: colors.background.header,
    headerTextColor: colors.text.secondary,

    // Rows
    oddRowBackgroundColor: colors.background.alternateRow,
    rowHoverColor: `${colors.background.base}cc`,
    selectedRowBackgroundColor: `${colors.signal.accent}15`,

    // Typography
    fontFamily: typography.fontFamily,
    fontSize: density.fontSize,
    headerFontSize: density.fontSizeXs,

    // Density-driven spacing
    rowHeight: density.rowHeight,
    headerHeight: density.headerHeight,
    cellHorizontalPaddingScale: density.paddingX / 8,

    // Borders
    borderColor: colors.border.primary,
    wrapperBorderRadius: 0,
  })
}

Canonical source: src/lib/data-grid/composer/theme-composer.ts

Pattern 8: Color Extraction Helpers

When: Extracting semantic colors from variant for custom UI.

typescript

export function extractStatusColors(variant: GridVariant) {
  return {
    active: variant.colors.signal.positive,
    pending: variant.colors.signal.warning ?? variant.colors.signal.accent,
    inactive: variant.colors.signal.neutral ?? variant.colors.text.muted,
    error: variant.colors.signal.negative,
    default: variant.colors.text.muted,
  } as const
}

export function extractFlashConfig(variant: GridVariant) {
  const flash = variant.colors.flash
  return {
    enabled: variant.behavior.microInteractions?.enableCellFlash ?? true,
    upColor: flash.up,
    downColor: flash.down,
    durationMs: flash.durationMs,
  }
}

Pattern 9: Legacy Basic Patterns

Theme Creation via themeQuartz (Direct)

typescript

import { themeQuartz } from 'ag-grid-community'
import { TMNL_TOKENS } from './data-grid-theme'

export const tmnlDataGridTheme = themeQuartz.withParams({
  backgroundColor: TMNL_TOKENS.colors.background,
  foregroundColor: TMNL_TOKENS.colors.text.primary,
  borderColor: TMNL_TOKENS.colors.border,
  headerBackgroundColor: TMNL_TOKENS.colors.surface,
  // ... etc
})

Basic Cell Renderer (Non-Context)

typescript

const IdCellRenderer = (params: ICellRendererParams) => (
  <span
    style={{
      color: TMNL_TOKENS.colors.text.muted,
      fontSize: TMNL_TOKENS.typography.sizes.xs,
      fontFamily: TMNL_TOKENS.typography.fontFamily,
      letterSpacing: '0.05em',
    }}
  >
    {params.value}
  </span>
)

Column Definitions

typescript

const columnDefs: ColDef[] = [
  {
    field: 'id',
    headerName: 'ID',
    width: 80,
    cellRenderer: IdCellRenderer,
    sortable: true,
  },
  {
    field: 'value',
    headerName: 'Value',
    width: 120,
    cellRenderer: ValueCellRenderer,
    comparator: (a, b) => a - b,
  },
]

Anti-Patterns (BANNED)

1. Importing CSS Files

typescript

// BANNED - No CSS imports with v34
import 'ag-grid-community/styles/ag-grid.css'
import 'ag-grid-community/styles/ag-theme-quartz.css'
// Use theme prop instead

2. Missing Module Registration

typescript

// BANNED - Grid will render blank
<AgGridReact rowData={data} columnDefs={cols} />
// Must register modules FIRST

3. useState for Grid Data

typescript

// BANNED when data crosses boundaries
const [rowData, setRowData] = useState([])
// Use Atom.make + service methods instead

4. Direct Theme Customization

typescript

// BANNED - Bypasses variant system
const theme = themeQuartz.withParams({ backgroundColor: '#123' })
// Use GridVariant + composeAgGridTheme() instead

5. Cell Renderer Without Context Fallback

typescript

// BANNED - Breaks outside grid context
function BadRenderer(params) {
  const ctx = useDataGridContext()  // Throws if no context!
  return <span style={{ color: ctx.variant.colors.text.primary }}>...</span>
}

// CORRECT - Graceful fallback
function GoodRenderer(params) {
  const ctx = useDataGridContextMaybe()
  const color = ctx?.variant.colors.text.primary ?? COLORS.textPrimary
  return <span style={{ color }}>...</span>
}

6. Creating Atoms Inside Components

typescript

// BANNED - Recreates on every render
function BadGrid() {
  const rowDataAtom = Atom.make([])  // BAD!
  return <AgGridReact ... />
}

// CORRECT - Module-level atoms
const rowDataAtom = Atom.make<RowData[]>([])
function GoodGrid() {
  const rowData = useAtomValue(rowDataAtom)
  return <AgGridReact rowData={rowData} ... />
}

Decision Tree: Which API to Use

Building a data grid?
│
├─ Simple, one-off grid?
│  └─ Use: Direct AgGridReact with composeAgGridTheme()
│
├─ Grid with header, status bar, controls?
│  └─ Use: Tmnl.DataGrid compound component
│
├─ Grid in tldraw shape?
│  └─ Use: V2 pattern (data-grid-shape-v2.tsx)
│
├─ Need real-time flash updates?
│  └─ Use: useFlashTracker + FlashValueRenderer
│
└─ Need custom variant?
   └─ Clone tmnlDenseDark and modify

File Locations Summary

Component	File	Purpose
Tmnl.DataGrid	`src/lib/data-grid/components/UnifiedDataGrid.tsx`	Compound component
DataGridContext	`src/lib/data-grid/components/DataGridContext.tsx`	Per-grid context
composeAgGridTheme	`src/lib/data-grid/composer/theme-composer.ts`	Variant → theme
Flash system	`src/lib/data-grid/flash/index.ts`	Cell highlighting
ValueCellRenderer	`src/lib/data-grid/renderers/ValueCellRenderer.tsx`	Context-aware
tmnlDenseDark	`src/lib/data-grid/variants/tmnl-dense-dark.ts`	Canonical variant
V2 tldraw shape	`src/components/tldraw/shapes/data-grid-shape-v2.tsx`	Modern integration
Hybrid drag	`src/components/tldraw/shapes/data-grid-shape.tsx:366-594`	Grid-to-canvas

Integration Points

effect-atom-integration — Atom-as-State for rowData
tmnl-design-tokens — Token fallbacks in renderers
common-conventions — Barrel exports, naming patterns
effect-patterns — Effect.Service for GridDragService

Search AI Tools

Install this agent skill to your Project

SKILL.md

AG-Grid Patterns for TMNL

Critical: AG-Grid v34 Module Registration

Canonical Sources

Core Library (v2)

tldraw Integration

Architecture Documentation

Pattern 1: Tmnl.DataGrid — COMPOUND COMPONENT API

Child Components

Per-Grid Runtime Isolation

Pattern 2: GridVariant System — VARIANT-DRIVEN THEMING

Variant Structure

Density Presets

Behavior Presets

Variant → Theme Conversion

Pattern 3: Flash System — CELL CHANGE HIGHLIGHTING

Severity Mapping

Flash State Structure

useFlashTracker Hook

Flash in Cell Renderer

Pattern 4: DataGridContext — PER-GRID SERVICES

Context Shape

Usage in Components

Color Extraction from Context

Pattern 5: Context-Aware Cell Renderers

Pattern: Fallback for Standalone Usage

Pattern: Flash-Aware Renderer

Pattern 6: Hybrid Drag System — GRID-TO-CANVAS

Drag Phase Transitions

Drag State Schema

Phase Handlers

Effect Service for Drag

Pattern 7: Theme Composition via composeAgGridTheme

Pattern 8: Color Extraction Helpers

Pattern 9: Legacy Basic Patterns

Theme Creation via themeQuartz (Direct)

Basic Cell Renderer (Non-Context)

Column Definitions

Anti-Patterns (BANNED)

1. Importing CSS Files

2. Missing Module Registration

3. useState for Grid Data

4. Direct Theme Customization

5. Cell Renderer Without Context Fallback

6. Creating Atoms Inside Components

Decision Tree: Which API to Use

File Locations Summary

Integration Points