Phase 5: Integration

Objective

Swap vendored grid components for canary equivalents in the canary-refactor stories, update barrel exports, remove placeholders, and validate with VRT.

Corresponds to General Workflow steps 5-8.

Entry Criteria

Phase 4 must be complete. Verify by checking artifacts — do NOT re-run tests.

Verify before starting:

• Tier 3a factory present: ls src/components/canary/organisms/shared/entity-data-grid/ shows create-entity-data-grid.tsx, use-dirty-tracking.ts, index.ts, test and story files
• Tier 3b shim present: ls src/components/canary/organisms/shared/entity-data-grid-shim/ shows create-entity-data-grid-shim.tsx, index.ts, test and story files
• ActionCellRenderer present: ls src/components/canary/atoms/grid/action/ shows action-cell-renderer.tsx
• Factory exports compile: grep 'createEntityDataGrid' src/components/canary/organisms/shared/entity-data-grid/index.ts confirms the export
• Shim exports compile: grep 'createEntityDataGridShim' src/components/canary/organisms/shared/entity-data-grid-shim/index.ts confirms the export
• Canary-refactor stories still exist (from Phase 0): ls src/canary-refactor/reference/items/ shows both story files
• Phase 4 exit gate passed: check for npm run lint + npm run test success in the Phase 4 terminal output (do not re-run)

Tasks

T5.1 — Fork Column Definitions

Fork vendored/arda-frontend/components/table/columnPresets.tsx into canary-refactor/components/columnPresets.tsx.

Update the forked file per the Column Definition Migration Map:

• Replace with canary atoms (~15 columns): SKU, GL Code, Sub-location, Sub-Type, Use Case, Department, Facility, Supplier SKU → TextCellDisplay. Min Qty Amount, Order Amount → NumberCellDisplay. Taxable → BooleanCellDisplay. Order Method, Card Size, Label Size, Breadcrumb Size → EnumCellDisplay/EnumCellEditor.
• Replace with new canary types (~3 columns): Notes, Card Notes → MemoButtonCell + createMemoButtonCellEditor() (vendored-compatible icon + modal pattern). Color → ColorCellDisplay/ColorCellEditor.
• Hybrid (~1 column): Supplier → canary TextCellDisplay for display, vendored SupplierCellEditor for editing.
• Retain vendored (~10 columns): Item name, Image, Unit Price, Order Cost, Created, Lead Time, Classification, Location, Quick Actions, Card Count.
• Remove: Select column (replaced by AG Grid native rowSelection in DataGrid<T>).

T5.2 — Fork ItemTableAGGrid

Fork vendored/arda-frontend/app/items/ItemTableAGGrid.tsx into canary-refactor/components/ItemTableAGGrid.tsx.

• Replace ArdaGrid import with canary createEntityDataGridShim<T>() (or DataGrid<T> directly if the shim isn’t needed for this context)
• Replace itemsColumnDefs / itemsDefaultColDef imports with the forked column definitions from T5.1
• Retain vendored imports for: all 9 typeahead cell editors, useItemCards context, API calls (createDraftItem, updateItem), constants (orderMethodOptions, etc.)
• Retain domain-specific draft lifecycle logic (this is the hybrid approach per Completeness #8)

T5.3 — Fork ItemsPage

Fork vendored/arda-frontend/app/items/page.tsx into canary-refactor/components/ItemsPage.tsx.

• Replace ItemTableAGGrid import with the forked version from T5.2
• Retain ALL other vendored imports: AppSidebar, AppHeader, SidebarProvider, ItemFormPanel, ItemDetailsPanel, CardsPreviewModal, ImportItemsModal, DeleteConfirmationModal, UI components, API calls, context hooks
• This is the page-level integration point

T5.4 — Fork ItemDetailPage

Fork vendored/arda-frontend/app/item/[itemId]/page.tsx into canary-refactor/components/ItemDetailPage.tsx.

• Replace ItemsPage import with the forked version from T5.3
• This is a thin wrapper — minimal changes

T5.5 — Update Canary-Refactor Stories

Update the canary-refactor stories (created in Phase 0) to import the forked page components:

• canary-refactor/reference/items/items-grid.stories.tsx — import ItemsPage from ../../components/ItemsPage (forked) instead of @frontend/app/items/page
• canary-refactor/reference/items/item-detail.stories.tsx — import ItemDetailPage from ../../components/ItemDetailPage (forked) instead of @frontend/app/item/[itemId]/page
• Update CSS import if needed: @/styles/vendored/globals.css → verify if canary styles need separate import

T5.6 — Run Lint, Build, Test (Workflow Step 5)

• npm run lint — verify no ESLint errors (canary imports only from canary + vendored via @frontend)
• npm run build:lib — verify library builds
• npm run test — verify all unit tests pass

T5.7 — Update Barrel Exports (Workflow Step 5, cont.)

Per Planning Q3 decision: update barrel at the end, remove placeholders.

Update src/canary.ts:

• Remove CanaryAtomPlaceholder, CanaryMoleculePlaceholder, CanaryOrganismPlaceholder exports
• Remove the placeholder component files themselves (components/canary/atoms/canary-placeholder/, components/canary/molecules/canary-placeholder/, components/canary/organisms/canary-placeholder/)
• Keep ArdaDetailField export (existing canary component)
• Add exports for all new canary components:
  • Cell atoms: TextCellDisplay, TextCellEditor, NumberCellDisplay, NumberCellEditor, BooleanCellDisplay, BooleanCellEditor, DateCellDisplay, DateCellEditor, EnumCellDisplay, EnumCellEditor, MemoCellDisplay, MemoCellEditor, MemoButtonCell, createMemoButtonCellEditor, ColorCellDisplay, ColorCellEditor
  • Molecule: DataGrid, DataGridRef, config types, PaginationData
  • Organisms: createEntityDataGrid, config/props/ref types, createEntityDataGridShim, shim types, ActionCellRenderer, RowAction
  • Hooks: useDirtyTracking

Update src/types/canary.ts:

• Add PaginationData export

T5.8 — VRT Comparison (Workflow Steps 7-8)

• Run VRT: npm run test:vrt
• Compare canary-refactor stories against dev-witness stories
• Expected: identical visual output (the canary grid infrastructure is a port, not a redesign)
• If VRT fails: document the differences, report to user for instructions per Workflow step 8

Acceptance Criteria

• Canary-refactor stories render the full Items page using canary grid infrastructure
• No vendored grid imports remain in canary-refactor stories (only vendored page chrome, panels, modals, domain editors retained via @frontend/ paths)
• ~15 columns use canary cell atoms, ~3 use new cell types (memo, color), ~10 retain vendored renderers
• canary.ts barrel exports all new components; placeholder components removed
• npm run lint + npm run build:lib + npm run test pass
• VRT comparison against dev-witness passes