Run 6: Item-grid Integration — Project Plan

Overview

Refactor item-grid to use entity-data-grid as its base instead of building directly on the DataGrid molecule. This is the core consolidation goal: proving that entity-data-grid’s promoted capabilities (Run 5) can absorb item-grid’s general-purpose framework code, leaving item-grid as domain-config only.

Repository: ux-prototype at /Users/jmp/code/arda/ux-prototype/ Branch: jmpicnic/component-consolidation Worktree (read-only reference): /Users/jmp/code/arda/callil-consolidation-worktree/

Entry Criteria

#	Criterion	Verification
E1	Run 5 exit gate passed	plan/run-5-entity-grid-evolution/validate-exit.sh returns 0
E2	Entity-data-grid has auto-publish, actions, search, pagination, toolbar, auto-height, drag-to-scroll	Stories for each capability render and pass in Storybook
E3	Branch clean, all Run 5 commits pushed	git status clean, git log shows Run 5 commits
E4	Baseline tests pass	npm run lint && npx tsc --noEmit && npm run test all green

Artifact Specifications

Artifact	Location	Description
Refactored item-grid	src/components/canary/organisms/item-grid/	item-grid delegating to entity-data-grid for all general-purpose capabilities
Updated item-grid stories	src/components/canary/organisms/item-grid/item-grid.stories.tsx	Stories working with refactored implementation
Updated item-grid tests	src/components/canary/organisms/item-grid/item-grid.test.tsx	Unit tests adapted to new internal structure
VRT baselines	VRT project config	Comparison against Run 3 baselines

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
6.1	Evaluate factory config vs wrapper	front-end-engineer	E1-E4	Pending	Written assessment: can item-grid be a pure createEntityDataGrid(itemGridConfig) call, or does it need a thin wrapper? Document which capabilities map to factory config, which need runtime wrapper logic. Decision recorded.
6.2	Create item-grid factory config or wrapper implementation	front-end-engineer	6.1	Pending	item-grid implemented using entity-data-grid as its base. No direct DataGrid molecule usage. npx tsc --noEmit passes.
6.3	Replace useItemGridEditing with entity-data-grid auto-publish	front-end-engineer	6.2	Pending	useItemGridEditing hook deleted or reduced to a thin adapter. Row editing lifecycle (edit, blur, save/error) delegated to entity-data-grid’s built-in auto-publish. onPublishRow callback wired through.
6.4	Replace inline search, drag-to-scroll, toolbar, actions with entity-data-grid capabilities	front-end-engineer	6.2	Pending	No inline search bar implementation in item-grid (uses entity-data-grid searchConfig). No inline drag-to-scroll (uses enableDragToScroll). No inline toolbar rendering (uses toolbar slot). No inline actions column (uses actionsColumn InitConfig).
6.5	Keep domain-specific code: curated columns, typeahead lookups, nested field value getters/setters, custom renderers	front-end-engineer	6.3, 6.4	Pending	item-grid still defines its 10 curated columns (Image, Name, SKU, GL Code, Classification, Supplier, Order Method, Unit Cost, Order Cost, Taxable, Notes). Typeahead lookups (ItemGridLookups) still work. Nested field value getters/setters (primarySupply.supplier, primarySupply.unitCost.value) still work. OrderMethod badge renderer, Notes icon renderer, Image thumbnail renderer all functional.
6.6	Update item-grid stories to work with refactored implementation	front-end-engineer	6.5	Pending	All existing item-grid story variants render: Default, Empty, Loading, WithSelection, WithSearch, Editable, Paginated, Composition. Stories use the same props/data as before. Play functions in Empty and WithSearch stories pass.
6.7	Update item-grid unit tests	front-end-engineer	6.5	Pending	All 6 existing item-grid tests pass. Tests adapted to new internal structure where necessary (e.g., if mocking entity-data-grid instead of DataGrid molecule). npm run test green.
6.8	Playwright MCP visual comparison against worktree item-grid stories	front-end-engineer	6.6	Pending	Navigate to each item-grid story in both Storybook instances. Screenshot comparison confirms visual equivalence: search filtering, editable cells with save lifecycle, selection count, pagination, actions column, drag-to-scroll. Discrepancies documented and justified.
6.9	VRT comparison against Run 3 baselines	front-end-engineer	6.6	Pending	npx playwright test --project=vrt run against item-grid stories. Comparison against Run 3 baselines. Expected: minimal or no visual diff (the refactoring is internal, not visual). Any diffs reviewed and baselines regenerated if changes are intentional.

Dependency Graph

E1-E4 (entry criteria)
  |
  v
6.1 Evaluate factory config vs wrapper
  |
  v
6.2 Create item-grid implementation
  |
  +-------+-------+
  |               |
  v               v
6.3 Replace      6.4 Replace search,
    editing          drag, toolbar, actions
  |               |
  +-------+-------+
          |
          v
        6.5 Keep domain-specific code
          |
          +-------+-------+
          |               |
          v               v
        6.6 Update      6.7 Update
            stories         tests
          |               |
          +-------+-------+
          |
          v
        6.8 Playwright MCP comparison
          |
          v
        6.9 VRT comparison

Parallelization: Tasks 6.3 and 6.4 can run in parallel (both modify item-grid internals but touch different capability areas). Tasks 6.6 and 6.7 can run in parallel (stories and tests are independent files). All other tasks are sequential.

Single agent: All tasks are assigned to a single front-end-engineer agent since they modify the same file set in the same directory. Parallelization is within-task (agent can work on 6.3 and 6.4 together), not across agents.

Exit Criteria

#	Criterion	Verification
X1	npm run lint passes	CI gate
X2	npx tsc --noEmit passes	CI gate
X3	npm run test passes (all existing + updated tests)	CI gate
X4	npm run build-storybook succeeds	CI gate
X5	Item-grid stories visually equivalent to pre-refactor (Run 3 baselines)	VRT comparison + Playwright MCP
X6	Entity-data-grid stories still pass (no regressions)	npm run test includes entity-data-grid tests
X7	No duplicated framework code between item-grid and entity-data-grid	Code review: no inline search, no inline drag-to-scroll, no inline toolbar, no inline actions column, no inline auto-publish in item-grid
X8	Item-grid play functions pass	npm run test:storybook or manual verification
X9	All Run 6 commits on jmpicnic/component-consolidation	git log

Agent Prompt Templates

front-end-engineer (all tasks)

You are refactoring item-grid to use entity-data-grid as its base.

Working directory: /Users/jmp/code/arda/ux-prototype/
Branch: jmpicnic/component-consolidation
Read-only reference: /Users/jmp/code/arda/callil-consolidation-worktree/

Key files:
- Item-grid organism: src/components/canary/organisms/item-grid/
- Entity-data-grid: src/components/canary/organisms/shared/entity-data-grid/
- DataGrid molecule: src/components/canary/molecules/data-grid/
- Item-grid molecules: src/components/canary/molecules/item-grid/

Analysis documents:
- Grid integration: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/grid-integration.md
- Blueprint Run 6: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/project-blueprint.md

The goal is to make item-grid delegate to entity-data-grid for ALL general-purpose
capabilities (auto-publish, search, toolbar, actions, drag-to-scroll, pagination,
auto-height). Item-grid should retain ONLY domain-specific code: curated columns,
typeahead lookups, nested field value getters/setters, custom renderers.

Start with task 6.1: read the entity-data-grid factory API (Run 5 output) and
compare against item-grid's requirements. Determine whether item-grid can be a
pure factory config call or needs a thin wrapper. Document your assessment.

After each task, run `npx tsc --noEmit` to verify compilation. After 6.5, run
`npm run test` to verify all tests pass.

Implementation Output

At run completion, write the following to implementation/run-6-item-grid-integration/:

Artifact	File	Description
Run summary	summary.md	What was done, decisions made during implementation, deviations from plan
Byproducts log	byproducts.md	Discovered issues, TODOs, observations for later runs
Validation output	validation-output.txt	Stdout from validate-exit.sh execution
Session log	session-log.md	Agent session IDs, timestamps, notable events

Path: documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/implementation/run-6-item-grid-integration/

Handoff

To Run 7 (Package API)

• All item-grid code now delegates to entity-data-grid
• No duplicated framework code remains
• Item-grid’s useItemGridEditing hook is deleted or reduced to a thin adapter
• Stories and tests pass
• VRT baselines for item-grid are current (regenerated if any visual changes occurred)

Key context for Run 7

• The refactoring may have changed item-grid’s export surface (e.g., if useItemGridEditing was deleted, it should no longer be in canary.ts barrel)
• Run 7 task 7.1 (barrel exports) should account for any exports added or removed in Run 6