@ornery/ui-grid-core — Agent Instructions

# @ornery/ui-grid-core — Agent Instructions

Pure TypeScript grid engine. Zero DOM dependencies. Provides the pipeline, sorting, filtering, grouping, pagination, cell editing, validation, export/import, infinite scroll, selection, tree-view, and i18n systems.

## Build & Test

```bash
npm run build:core           # tsup → dist/
npm test --prefix projects/ui-grid-core   # vitest (154 tests)
```

## Key Modules

| File | Responsibility |
|------|---------------|
| `grid.models.ts` | All shared interfaces (`GridOptions`, `GridColumnDef`, `GridRecord`, etc.) |
| `grid.api.ts` | `UiGridApi` — the public event/method surface consumers use |
| `grid.core.pipeline.ts` | Row pipeline: filter → sort → group → tree → paginate → virtualize |
| `grid.core.viewmodel.ts` | Pure functions: `gridColumnWidth`, `gridCellIndent`, display value formatting |
| `grid.core.filtering.ts` | Filter predicate logic |
| `grid.core.grouping.ts` | Group-by column aggregation |
| `grid.core.edit.ts` | Cell edit begin/commit/cancel commands |
| `grid.core.export.ts` | CSV/PDF export pipeline |
| `grid.core.i18n.ts` | Label resolution (`resolveGridLabels`) |
| `grid.core.selection.ts` | Row selection state machine |
| `grid.core.infinite-scroll.ts` | Infinite scroll state + direction management |
| `grid.core.validate.ts` | Cell validation registry |
| `grid.core.save-state.ts` | Save/restore grid state |
| `grid.constants.ts` | `SORT_DIRECTIONS`, feature-flag helpers |

## Architecture Rules

- **No DOM.** This package must never import browser APIs. It runs in Node, WASM, and browser alike.
- **Pure functions preferred.** State lives in the controller (vanilla package); core provides stateless transforms.
- **`GridOptions` is the source of truth.** Every feature is toggled via `enable*` booleans on `GridOptions`.
- **Pipeline is composable.** `defaultGridEngine.buildPipeline()` chains all transforms; the result is a `PipelineResult` with `displayItems` and `visibleRows`.

## Adding a Feature

1. Define types in `grid.models.ts`.
2. Add the pure logic in a new `grid.core.<feature>.ts` file.
3. Wire it into the pipeline in `grid.core.pipeline.ts` if it affects row visibility/order.
4. Expose API events/methods in `grid.api.ts`.
5. Export everything from the barrel `index.ts`.
6. The vanilla controller consumes the new exports; core never consumes vanilla.

## Do NOT

- Add DOM or browser imports
- Mutate input arrays — always return new arrays/objects
- Add default exports — use named exports only
- Break the build order: core has no internal monorepo deps