Image Upload Components — Suggestions

Improvement opportunities identified during the image upload component implementation.

S-01: Add ESLint `no-restricted-imports` rule for `mocks/`

Category: Technical debt prevention

Production component files should never import from __mocks__/ directories. This was caught and fixed during the audit, but could recur. Add an ESLint rule:

{
  "no-restricted-imports": ["error", {
    "patterns": [{
      "group": ["*/__mocks__/*"],
      "message": "Mock imports are only allowed in *.test.tsx and *.stories.tsx files."
    }]
  }]
}

Apply the override to allow __mocks__/ imports in test and story files only.

S-02: Add an interactive story for ImageComparisonLayout

Category: Documentation gap

The only open item from the inconsistencies audit (#7). The current DesktopSideBySide story uses alert() callbacks for Accept/Dismiss/Upload New. A more complete story should show state transitions (image updated, layout reset) similar to the DoubleClickToEdit story in ImageDisplay.

Effort: Low.

S-03: Consider Avatar rewrite to compose ImageDisplay

Category: Future simplification

Documented in follow-up-work.md. Once ImageDisplay is proven in production, Avatar could become a thin wrapper that passes imageUrl and entityName to ImageDisplay with a displayShape: 'circle' config. This would consolidate the two image rendering paths (loaded/loading/error states defined once).

Prerequisites: Add displayShape: 'square' | 'circle' to ImageFieldConfig. Verify all existing Avatar stories render correctly.

Trigger: User profile image editing use case.

S-04: Run `enforce-story-order.js` in CI

Category: Process improvement

The tools/enforce-story-order.js script validates that Playground stories are exported last in every story file. Currently it must be run manually. Adding it to the lint npm script or as a pre-commit check would prevent sidebar ordering regressions.

S-05: Audit specification for completeness before multi-run projects

Category: Process improvement

The original specification defined 19 components with full props interfaces and story lists, but did not specify interaction wiring — which component owns the dialog lifecycle, where state lives, how components compose. This led to externalized interactions in Runs 1-3 that had to be reworked in post-run refinements.

For future multi-run component projects, the specification should include an interaction ownership matrix: for each user-facing action (edit, inspect, remove, upload), which component owns the trigger, the state, and the completion callback.

S-06: ImageUploadDialog needs real upload handler injection point

Category: Backend integration readiness

The dialog currently accepts onUpload and onCheckReachability via ImageFieldConfig. The mock implementations use setTimeout + random success/failure. When integrating with the real backend:

onUpload should accept a File and return { imageUrl: string } or throw with a structured error.
onCheckReachability should ping the presigned-POST endpoint to verify the upload target is reachable before starting.
Consider adding an AbortController signal to support upload cancellation.

The prop interfaces are ready; the concern is testing — the current test suite only exercises mock upload paths.