Run 4: Grid Atoms, Organism, and Integration

Implements Wave 3 (grid atoms), Wave 4 (ImageUploadDialog organism and integration), and the final barrel-export pass. This is the terminal run of the Item Image Upload component implementation plan.

Base branch: jmpicnic/item-image-upload-components (branched from main)

Entry Criteria

Run 3 exit gate passed: lint, build-storybook, and test all exit 0 on the base branch.
Base branch jmpicnic/item-image-upload-components contains all Run 3 commits.

Artifact Specifications

4.1 — ImageCellDisplay

Property	Value
Type	Atom (grid)
Location	`src/components/canary/atoms/grid/image/image-cell-display.tsx`
Tests	6
Stories	8 (in `image.stories.tsx` with a simplified 4-column AG Grid)
Depends on	ImageHoverPreview (Run 3), ImageDisplay (Run 2)

Acceptance Criteria:

Grid story renders all four visual states: empty, loading, loaded, error.

4.2 — ImageCellEditor

Property	Value
Type	Atom (grid)
Location	`src/components/canary/atoms/grid/image/image-cell-editor.tsx`
Tests	5
Stories	1 (EditorFactoryDemo, co-located in `image.stories.tsx`)
Factory	`createImageCellEditor`
Depends on	ImageUploadDialog (4.3)

Acceptance Criteria:

getValue ref handle returns the current value correctly.
createImageCellEditor factory returns a valid AG Grid cell editor component.

4.3 — ImageUploadDialog

Property	Value
Type	Organism
Location	`src/components/canary/organisms/shared/image-upload-dialog/`
Tests	15
Stories	9
Depends on	ImageDropZone (Run 2), ImageComparisonLayout (Run 3), ImagePreviewEditor (Run 2), CopyrightAcknowledgment (Run 2), getCroppedImage (Run 1)

Acceptance Criteria:

State machine transitions (idle → uploading → cropping → confirming → done) work correctly and are testable via unit tests.
Copyright gate blocks submission until acknowledgment is confirmed.
Warn-on-discard dialog fires when closing with unsaved changes.

4.4 — Image Grid MDX Documentation

Property	Value
Type	MDX documentation
Location	`src/components/canary/atoms/grid/image/image.mdx`
Tests	—
Stories	—
Depends on	ImageCellDisplay (4.1), ImageCellEditor (4.2)

Acceptance Criteria:

MDX renders in Storybook without acorn/JSX parse errors.
Canvas embeds reference published story IDs correctly.

4.5 — item-grid-columns Integration

Property	Value
Type	Modification (existing file)
Location	`src/components/canary/organisms/shared/item-grid-columns/`
Tests	— (covered by existing test suite)
Stories	— (existing stories verified)
Depends on	ImageCellDisplay (4.1)

Acceptance Criteria:

Inline ImageCellRenderer replaced with ImageCellDisplay import.
Existing item-grid stories render identically to their pre-Run-4 baselines.

4.6 — Barrel Exports

Property	Value
Type	Integration
Location	`src/canary.ts`
Tests	—
Stories	—
Depends on	All tasks 4.1–4.5

Acceptance Criteria:

All new components and types are exported from @arda-cards/design-system/canary.
node tools/update-package-contents.js completes without error.

Task List

Task	Description	Tests	Stories	Status
4.1	ImageCellDisplay atom	6	8	Pending
4.2	ImageCellEditor atom	5	1	Pending
4.3	ImageUploadDialog organism	15	9	Pending
4.4	Image grid MDX documentation	—	—	Pending
4.5	item-grid-columns modification	—	—	Pending
4.6	Barrel exports	—	—	Pending
Total		26	18

Internal Dependency Graph

Task 4.3 (ImageUploadDialog) is the critical path — it is the largest and most complex component. Task 4.1 (ImageCellDisplay) is independent of 4.3 and may be implemented in parallel. All remaining tasks gate on 4.1 or 4.3.

4.3 ImageUploadDialog ─────────────────────────────────────┐
                                                            │
4.1 ImageCellDisplay ──► 4.2 ImageCellEditor (needs 4.3) ──┤
                    │                                       │
                    └──► 4.5 item-grid-columns ─────────────┤
                                                            │
        4.4 Image MDX (needs 4.1 + 4.2) ───────────────────┤
                                                            │
                              4.6 Barrel exports ◄──────────┘
                                (depends on all)

Exit Criteria

All of the following must pass before the PR is opened:

npm run lint exits 0 (zero warnings).
npm run build-storybook exits 0.
npm run test exits 0.
26 new unit tests pass (cumulative count includes Runs 1–3 tests).
18 new Storybook stories render without console errors.
All new components and types are importable from @arda-cards/design-system/canary.
node tools/update-package-contents.js completes without error.

Handoff

Run 4 is the terminal run. On exit gate passage, the feature branch is ready for pull request review and merge. There are no downstream runs.

Artifact	State
Complete component library (19 components)	Ready for PR
Full Storybook (all stories + MDX)	Ready for stakeholder review
Barrel exports in `canary.ts`	Ready for consumer repositories