Phase 2: Standardized AG Grid

Phase 2: Standardized AG Grid

Status: Planning Repository: ux-prototype (build), arda-frontend-app (test via linking) Parent: Vendor Page and Standard Layout

Goal

Make the design system’s data grid production-ready by standardizing input components, building cell editors as variants of those inputs, and filling gaps in the createEntityDataGrid factory. The result is a grid component that can replace hand-rolled grids in arda-frontend-app starting with the vendor page (Phase 3).

Approach

Work happens in ux-prototype. Testing happens in arda-frontend-app via npm run dev:local (linked builds). Multiple PRs expected as we touch many files across the input and grid systems.

Development workflow

1. Build/refine inputs and cell editors in ux-prototype
2. Link repos via npm run dev:local in arda-frontend-app
3. Validate against real data and interactions in the frontend app
4. PR to ux-prototype when a coherent slice is complete
5. Repeat

Scope

Part A: Input Audit and Standardization

Audit all input atoms to establish consistent interaction patterns across every input type. The goal is parallel behavior: once a user learns how one input works, every other input works the same way.

Interaction states to standardize:

State	Expected Behavior (all input types)
Idle	Default appearance, border-input, text-foreground
Hover	Subtle border change (border-border-strong)
Focus	Ring treatment (ring-2 ring-ring), border highlight
Blur	Validate, commit value, remove ring
Disabled	Reduced opacity, no pointer events
Error	Destructive border, error message below
Read-only	Display value without input chrome

Keyboard interactions to standardize:

Key	Expected Behavior (all input types)
Tab	Move focus to next input
Shift+Tab	Move focus to previous input
Enter	enter edit state? or Commit value
Escape	Exit edit state?
Arrow keys	Navigate the grid in every direction when not in edit state. When in edit state navigate inside of input (select: cycle options; number: increment/decrement if set to true number fields should have this as boolean property)
Copy/Paste	Standard clipboard behavior, respect input constraints. Works in edit state or view state.

Input types to audit:

• Text input
• Number input
• Select / dropdown
• Typeahead / combobox
• Date picker
• Date-time picker
• Time picker
• Boolean (checkbox / toggle)
• Color picker
• Image upload
• Memo / multi-line text
• Money (number + currency)
• Quantity (number + unit)
• Duration (number + time unit)
• URL input
• Merged cells (Allows creation of groups or divider lines)

Deliverables:

• Interaction audit document (current state vs target state per input type)
• Standardized base styles and interaction patterns
• Updated Storybook stories showing all states for each input
• Consistent keyboard behavior across all inputs

Part B: Cell Editors as Input Variants

Build grid cell editors as thin wrappers around the standardized inputs from Part A. Each cell editor adapts a standard input for the AG Grid editing context (inline, constrained height, keyboard navigation between cells).

Cell-specific interaction layer:

Trigger	Grid Behavior
Single click	Select row (no edit)
Double click	Enter edit mode on cell
Enter (on selected cell)	Enter edit mode
Enter (while editing)	Commit value, exit edit mode, move to next row
Tab (while editing)	Commit value, move to next editable cell
Shift+Tab (while editing)	Commit value, move to previous editable cell
Escape (while editing)	Exit edit mode
Arrow keys (while editing)	Navigate within editor (not between cells)
Arrow keys (not editing)	Navigate between cells
Ctrl+Z	Undo edits sequentially
Copy and Paste	Always works if the object in the clipboard matches the input type. Do not need to be in edit mode. Focus ring turns red for a second and standard alert at the top of screen says “invalid input”

Cell editor types (corresponding to inputs):

Cell Editor	Wraps Input	Notes
TextCellEditor	Text input	Single-line inline
NumberCellEditor	Number input	Numeric constraints, formatting on blur, boolean for up down arrow incrementing
SelectCellEditor	Select	Dropdown opens on edit, keyboard navigable
TypeaheadCellEditor	Typeahead	Async lookup, create-new option, max list length prop (negative number for infinite, 0 or null defaults to 8)
DateCellEditor	Date picker	Calendar dropdown
BooleanCellEditor	Checkbox	Toggle on click or Space or enter, no double-click needed
ColorCellEditor	Color picker	Swatch grid dropdown
ImageCellEditor	Image upload	Thumbnail + upload trigger, drag and drop should work without entering edit mode
MemoCellEditor	Memo	Expands to multi-line overlay
Money/Prefix CellEditor	Money	Number + currency display, dropdown for editing prefix when in edit mode (focus defaults to value, shift tab to focus on prefix)

Bulk editing (multi-cell selection):

Users should be able to select multiple cells and apply a single edit to all of them — for example, selecting 10 rows and changing a dropdown value, or pasting a value across a range. AG Grid Enterprise provides enableRangeSelection and enableFillHandle for this. Evaluate whether Community edition’s clipboard support is sufficient or if Enterprise range selection is needed.

Bulk Action	Expected Behavior
Select range + type value	Apply typed value to all selected cells of the same column
Select range + paste	Paste clipboard content across selected cells
Select range + dropdown change	Apply selected dropdown value to all cells in range
Fill handle drag	Extend a cell’s value down/across like a spreadsheet
Select range + Delete/Backspace	Clear all selected cells

Add row:

The grid must support adding a new row inline. This creates a blank row at the top (or bottom, configurable) of the grid in edit mode. The consumer provides an onRowAdd callback prop that receives the new row data and is responsible for the API call to persist it. The grid itself is not opinionated about the backend — it just provides the UI and calls the prop.

Behavior	Details
Trigger	”Add row” button above grid (or keyboard shortcut)
New row position	Top of grid (default), configurable
Initial state	Edit mode on first editable cell, all fields empty or defaults
Commit	Enter or Tab out of last cell → calls onRowAdd(rowData)
Cancel	Escape → removes the uncommitted row
Validation	Cell-level validation runs before commit; row not saved until all cells valid

Row grouping / hierarchy:

AG Grid has built-in row grouping (groupDisplayType, rowGroup on ColDef) that we should leverage directly. This enables tree-structured data views like supplier → items, category → subcategory → items, etc.

Feature	AG Grid Capability	Edition
Single-column grouping	rowGroup: true on ColDef	Enterprise
Multi-column grouping	Multiple rowGroup columns	Enterprise
Group row rendering	groupRowRenderer	Enterprise
Expand/collapse	Built-in with groupDefaultExpanded	Enterprise
Aggregation in group rows	aggFunc on ColDef	Enterprise
Tree data (arbitrary hierarchy)	treeData: true + getDataPath	Enterprise

Note: Row grouping requires AG Grid Enterprise. If we want to avoid the Enterprise dependency, we’d need to implement grouping at the data layer (pre-group rows before passing to the grid), which is what the current order queue page does manually.

Grouped/composite columns:

Some data is logically grouped — values that belong together and should display as a single cell but split apart when editing. Examples:

Grouped Column	Component Fields	Display	Edit Mode
Min Quantity	amount + unit	”10 each”	Two inputs side by side (number + select)
Order Quantity	amount + unit	”100 boxes”	Two inputs side by side
Unit Cost	value + currency	”$5.00 USD”	Number + currency dropdown
Address	street#, street, city, state, zip, country	”123 Main St, Austin, TX 78701”	Multi-field form (expandable)
Duration	length + unit	”3 days”	Number + time unit select

Grouped column behaviors:

• Display as one cell — combined formatted value in read mode
• Split on edit — expand into component inputs when editing
• Move together — reordering a grouped column moves all component fields as a unit
• Resize together — the group shares a single column width
• Sort by primary field — sort uses the first component (e.g. amount for quantity, value for money)
• Validation cascades — changing one field may invalidate others (e.g. changing country invalidates state; address validation may need to validate the full composite via a dropdown/lookup)

This pattern mirrors a broader need for form groups/composite inputs — reusable multi-field components like an Address input that combines several independent inputs (street, city, state, country) where:

• Some sub-inputs can exist independently (state, country dropdowns)
• Changing one sub-input may invalidate or constrain others
• The composite may have its own validation (e.g. address verification API)
• The same composite appears in both form mode and cell editor mode

The cell editor architecture (Open Question #7) should account for composite editors — a grouped cell editor wraps multiple inputs and manages their internal layout, focus order, and cross-field validation.

Cell display components:

Each cell type also has a display variant (read-only rendering) that matches the visual language of the editor. Display components handle formatting (currency symbols, date formatting, color swatches, image thumbnails, etc.).

Deliverables:

• Cell editors wrapping standardized inputs (factory pattern: createXCellEditor())
• Cell display components with consistent formatting
• Storybook stories showing edit lifecycle for each cell type
• Documentation of cell interaction model

Part C: Grid Production-Readiness

Fill gaps in createEntityDataGrid to make it production-ready. The current factory provides the foundation but is missing features the production ArdaGrid has.

Gap analysis (prototype vs production ArdaGrid):

Feature	Prototype (createEntityDataGrid)	Production (ArdaGrid)	Action
Column persistence	useColumnPersistence hook	Complex inline localStorage logic	Keep prototype pattern, verify completeness
Sort UI	AG Grid default	Custom SortMenuHeader with portal dropdown	Evaluate: adopt custom header or use AG Grid default
Server pagination	Supported via config	Supported + page size selector	Add page size selector
Row editing + auto-publish	Built-in via useRowAutoPublish	Manual draft/publish in parent	Keep prototype pattern
Cell editing	Factory-pattern editors	Hand-rolled per-domain editors	Standardize in Part B
Enterprise features	Community edition	Enterprise modules (optional)	Support optional enterprise license
Search	Built-in client-side	Not built into grid	Keep prototype search
Filtering	Not built in	AG Grid column filters	Add configurable filtering
Empty state	Configurable component	Overlay-based	Keep prototype pattern
Loading state	Supported	Skeleton overlays	Align approaches
Selection	Checkbox column	Checkbox + stable row IDs	Verify stable selection
Drag-to-scroll	Supported	Not in ArdaGrid	Keep
Sticky columns/rows	Not implemented	Action column pinned right	Add configurable pinning (columns and rows)
Column visibility & ordering	Not implemented	Custom UI — users toggle and reorder columns, saved per tenant	Must preserve — port to design system grid
Column layout presets	Not implemented	Not implemented	Future: let users save named column layouts and switch between them for different workflows

Note: Filtering and infinite scroll using Server-Side Row Model are coming to the Arda grid in the coming days. We will have to capture this functionality.

Row height configurability (nice-to-have):

Support a density prop on the grid:

Density	Row Height	Use Case
compact	32px	Dense data views (items list, order queue)
comfortable	40px	Default, balanced
spacious	48px	Touch-friendly, fewer rows (mobile, receiving)

Consumer sets density at the grid level; all rows respect it.

Deliverables:

• Updated createEntityDataGrid factory with gap fixes
• Configurable filtering support
• Page size selector for server pagination
• Optional enterprise module support
• Row height / density prop (nice-to-have)
• Sticky/pinned column and row support (configurable per ColDef)
• Column visibility and ordering UI (port existing ArdaGrid feature)
• Column layout persistence per tenant (preserve existing behavior)
• Updated stories and documentation

Future (not in Phase 2 scope but design for it):

• Column layout presets — users save named configurations (e.g. “Ordering view”, “Receiving view”) and switch between them. The persistence layer should be designed to support multiple named layouts per grid per tenant, even though Phase 2 only implements a single default layout.

Existing Assets (Starting Points)

In ux-prototype (build on these)

Asset	Path	Notes
DataGrid molecule	canary/molecules/data-grid/	Low-level AG Grid wrapper
EntityDataGrid factory	canary/organisms/shared/entity-data-grid/	Main factory (~650 lines)
EntityDataGrid shim	canary/organisms/shared/entity-data-grid-shim/	Tier 3b extensions
Cell atoms (10 types)	canary/atoms/grid/	text, number, select, boolean, date, color, image, memo, action, typeahead
Column persistence hook	canary/molecules/data-grid/use-column-persistence.ts	localStorage with namespacing
Row auto-publish hook	canary/organisms/shared/entity-data-grid/use-row-auto-publish.ts	Per-row dirty tracking
Item grid columns	canary/molecules/item-grid/item-grid-columns.tsx	Column def factory
Item grid organism	canary/organisms/item-grid/	Item-specific grid
Kitchen sink stories	canary/organisms/shared/entity-data-grid/kitchen-sink.stories.tsx	Comprehensive demo

In arda-frontend-app (reference, not build here)

Asset	Path	Notes
ArdaGrid	components/table/ArdaGrid.tsx	Production grid (~1328 lines)
Column presets	components/table/columnPresets.tsx	30+ column defs (~1500 lines)
Domain cell editors (9)	components/items/*CellEditor.tsx	Supplier, Type, Location, etc.
ItemTableAGGrid	app/items/ItemTableAGGrid.tsx	Item page grid
OrderQueueAGGrid	app/order-queue/OrderQueueAGGrid.tsx	Order queue grid

AG Grid Built-in Feature Audit

Before building custom implementations, we need to audit what AG Grid already provides out of the box. Many of the features listed in this spec (cell editors, keyboard navigation, clipboard, undo/redo, validation, filtering, column persistence) are available as built-in AG Grid capabilities — either in the Community or Enterprise edition.

The current ArdaGrid and columnPresets.tsx in arda-frontend-app contain ~2,800 lines of hand-rolled grid logic. A significant portion may duplicate functionality that AG Grid provides natively. We need to determine:

1. What AG Grid already does — which features in our spec have direct AG Grid equivalents (built-in cell editors, cellEditorParams, undo via undoRedoCellEditing, clipboard via enableRangeSelection, etc.)?
2. Why it wasn’t used — was there a technical reason (incompatibility with our UI patterns, limitations in the Community edition, Radix portal conflicts) or was it simply a gap in awareness at the time?
3. What we should adopt vs wrap — for each feature, decide whether to:
   • Adopt the AG Grid built-in directly (no custom code)
   • Wrap the built-in with a thin styling/behavior layer
   • Replace with a custom implementation (only when AG Grid’s version genuinely doesn’t work for our use case)

This audit should happen at the start of Part A and inform the scope of Parts B and C. Adopting built-in features where possible reduces our maintenance burden and keeps us on the upgrade path for future AG Grid versions.

Known AG Grid built-ins relevant to this spec:

Feature	AG Grid Capability	Edition	Our Current Approach
Cell editors (text, number, select, date)	agTextCellEditor, agNumberCellEditor, agSelectCellEditor, agDateCellEditor	Community	Hand-rolled per domain
Keyboard navigation (Enter, Tab, Escape, arrows)	Built-in with enterNavigatesVertically, tabToNextCell	Community	Partially custom
Undo/Redo	undoRedoCellEditing, undoRedoCellEditingLimit	Community	Not implemented
Clipboard copy/paste	enableCellTextSelection, clipboardDelimiter	Community	Not implemented
Range selection + fill handle	enableRangeSelection, enableFillHandle	Enterprise	Not implemented
Column state persistence	columnApi.getColumnState() / applyColumnState()	Community	Custom useColumnPersistence hook
Filtering (column filters)	agTextColumnFilter, agNumberColumnFilter, agSetColumnFilter	Community/Enterprise	Not built in
Row sorting	Built-in with sortable: true	Community	Custom SortMenuHeader
Validation	valueSetter with validation logic	Community	Not standardized
Row height	rowHeight, getRowHeight	Community	Fixed per grid
Pinned/sticky columns	pinned: 'left' / pinned: 'right' on ColDef	Community	Used on some columns (actions)
Pinned/sticky rows	pinnedTopRowData, pinnedBottomRowData	Community	Not implemented
Column visibility & reorder	columnApi.setColumnsVisible(), drag reorder, suppressMovable	Community	Custom column visibility UI in ArdaGrid

Current Enterprise usage in arda-frontend-app:

ArdaGrid.tsx registers AllEnterpriseModule (all Enterprise features available). Currently only rowGroup is actively used (in OrderQueueAGGrid for supplier/order method grouping). The following Enterprise features are licensed and available but unused — these should be evaluated before building custom alternatives:

• enableRangeSelection — multi-cell selection (needed for bulk edit)
• enableFillHandle — drag to extend values (spreadsheet-style)
• agSetColumnFilter — set-based column filtering
• Server-Side Row Model — infinite scroll with server pagination
• Tree Data — arbitrary hierarchy display
• Clipboard with range — paste across selected cell ranges

Open Questions

#	Question	Options	Recommendation	Decision
1	Should we adopt ArdaGrid’s custom SortMenuHeader or use AG Grid’s built-in sort?	A) Port SortMenuHeader to design system; B) Use AG Grid default; C) Build new	B — use AG Grid built-in sort	Use AG Grid default
2	How should cell validation errors display?	A) Inline below cell; B) Tooltip on hover; C) Cell border + row-level error summary	Cell shakes and reverts to previous value. A toast shows at the top of the screen explaining the error. For bulk edits, a single persistent toast lists all errors (user must manually dismiss). AG Grid provides isCancelAfterEnd() and getValidationErrors() hooks on cell editors for this.	Shake + toast
3	Should inputs support both “form mode” and “cell mode” via a prop, or should cell editors be separate components that share styles?	A) Single component with mode prop; B) Separate components sharing base styles; C) Use AG Grid’s cellDataType + dataTypeDefinitions system	AG Grid already solves this. Cell editors are controlled components receiving value + onValueChange — the same contract as React form inputs. AG Grid’s cellDataType system auto-wires editors, renderers, formatters, and filters from a single declaration (e.g. cellDataType: 'number'). Custom data types extend built-in ones. Our inputs should be built as standalone components that also conform to AG Grid’s CustomCellEditorProps contract (value, onValueChange). No wrapper needed — the input IS the editor. See OQ#7 for details.	Align with AG Grid contract
4	How much of our custom grid code duplicates AG Grid built-ins?	A) Audit and adopt built-ins where possible; B) Keep custom implementations	A — audit first, replace where AG Grid’s version meets our needs, document reasons where it doesn’t	Pending
5	Where should column layout persistence live?	A) localStorage per tenant (current); B) Backend API per user-account; C) Both with sync	Keep current Redux persist / localStorage pattern for v1. Backend UserAccount.settings field available for future cross-device sync but not addressed in this phase.	localStorage (v1)
6	Should column layout presets be per-grid or global?	A) Per-grid (items grid has its own presets); B) Global presets applied to any grid	A — per-grid. Each grid instance has different data and use cases. Not addressed in v1; the persistence layer should be designed to support named presets per grid for a future version.	Per-grid (future)
7	Cell editor architecture: generic wrapper or per-input?	A) Each input is a standalone cell editor; B) Generic GridCellEditor wrapper; C) HOC/factory; D) Align with AG Grid’s native contract	D — AG Grid’s cell editor contract is already minimal and matches React input conventions. A cell editor is a controlled component with value + onValueChange props, plus optional lifecycle hooks via useGridCellEditor (isCancelBeforeStart, isCancelAfterEnd, focusIn). AG Grid also provides cellDataType / dataTypeDefinitions to auto-wire editors from a type declaration. Our approach: build each input as a standard React component that accepts value + onChange. To use it as a cell editor, either (a) it already matches CustomCellEditorProps directly, or (b) wrap it in a thin adapter that maps onChange → onValueChange and adds useGridCellEditor for validation. Shared grid behavior (shake on error, toast) lives in the adapter or a shared hook, not in every input. See “AG Grid Cell Editor Architecture” section below.	AG Grid native + thin adapter
8	Do we need AG Grid Enterprise for this phase?	A) Community only; B) Enterprise for range selection, grouping, tree data; C) Enterprise optional (degrade gracefully)	Already resolved: arda-frontend-app has Enterprise v34.3.1 with a license key (ArdaGrid.tsx line 35). The ux-prototype uses Community only. Decision: the design system grid should work with Community for Storybook/dev, but detect and enable Enterprise features (range selection, row grouping, fill handle, set filters) when the consumer provides a license. The consumer (arda-frontend-app) already has one.	Enterprise available

AG Grid Cell Editor Architecture

Based on AG Grid’s documented contract, cell editors are controlled components — they receive value and onValueChange as props. This is nearly identical to how standard React inputs work (value + onChange).

AG Grid’s cell editor contract:

// AG Grid expects this shape (CustomCellEditorProps)
interface CustomCellEditorProps {
  value: any;
  onValueChange: (value: any) => void;
  // Plus context: column, colDef, data, node, rowIndex, eventKey,
  // stopEditing(), eGridCell, parseValue(), formatValue(), validate()
}

AG Grid’s cellDataType system:

Instead of manually wiring editors per column, you declare a data type once and AG Grid auto-selects the editor, renderer, formatter, and filter:

// Column definition — just declare the type
{ field: 'unitCost', cellDataType: 'currency' }

// Grid-level — define custom data types
const dataTypeDefinitions = {
  currency: {
    extendsDataType: 'number',
    baseDataType: 'number',
    valueFormatter: params => `$${params.value?.toFixed(2)}`,
    // Automatically uses NumberCellEditor, or our custom one if registered
  }
};

Recommended architecture for our inputs:

┌─────────────────────────────────────────────┐
│  Standard Input Component                    │
│  (TextInput, NumberInput, Select, etc.)       │
│  Props: value, onChange, onBlur, error, ...   │
│  Works in forms, dialogs, standalone          │
└──────────────────┬──────────────────────────┘
                   │
        ┌──────────▼──────────┐
        │  Cell Editor Adapter │  (thin, per-input-type)
        │  Maps onChange →     │
        │    onValueChange     │
        │  Adds useGridCell-   │
        │    Editor hooks:     │
        │  - isCancelAfterEnd  │
        │    (validation)      │
        │  - focusIn/focusOut  │
        │  Shake + toast on    │
        │    validation fail   │
        └──────────┬──────────┘
                   │
        ┌──────────▼──────────┐
        │  AG Grid renders it  │
        │  as a cell editor    │
        │  via cellDataType or │
        │  colDef.cellEditor   │
        └─────────────────────┘

Key decisions:

1. Inputs are NOT AG Grid-aware. They are standard React components with value + onChange. They work anywhere — forms, dialogs, sidebars.
2. Cell editor adapters are thin. Each adapter maps onChange → onValueChange, adds useGridCellEditor hooks for validation, and handles grid-specific behavior (shake animation, toast on error).
3. Shared grid behavior lives in a hook. A useGridCellValidation hook (or similar) provides the shake + toast pattern so each adapter doesn’t re-implement it.
4. cellDataType wires it up. Custom data types in dataTypeDefinitions auto-select the right adapter-wrapped editor per column — no manual cellEditor prop needed on each ColDef.
5. Composite editors (quantity+unit, money+currency, address) are adapters that render multiple inputs internally and manage their own focus order and cross-field validation.

Exit Criteria

• AG Grid built-in feature audit completed — documented which built-ins we adopt, wrap, or replace (and why)
• All input types have consistent interaction states (hover, focus, blur, error, disabled)
• All input types have consistent keyboard behavior (Enter, Escape, Tab, arrows)
• Cell editors wrap standardized inputs via generic wrapper/factory (shared grid behavior)
• Bulk edit works — multi-cell selection, paste across range, dropdown apply to range
• Add row works — inline new row with onRowAdd callback prop for backend persistence
• Row grouping/hierarchy supported (Enterprise) with graceful Community fallback
• Sticky/pinned columns and rows configurable per ColDef
• Column visibility and ordering UI ported from ArdaGrid
• Column layout persistence works (localStorage, designed for future backend sync)
• createEntityDataGrid supports configurable filtering
• Grid works with linked arda-frontend-app via npm run dev:local
• Storybook stories demonstrate all cell types in edit lifecycle
• No regressions in existing grid stories

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved