Jean-Luc Makiola
407fa45280
Archive v1.1 artifacts (roadmap, requirements, phases) to milestones/. Evolve PROJECT.md with shipped requirements and new key decisions. Reorganize ROADMAP.md with collapsed milestone groupings. Update retrospective with v1.1 lessons. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# Phase 5: Image Handling - Context
|
|
|
|
**Gathered:** 2026-03-15
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Fix image display throughout the app (images upload but don't render), redesign the upload UX with a hero image preview area and placeholder icons, and add image display to gear cards, candidate cards, and setup item lists. No new image features (galleries, editing, tagging) — those would be separate phases.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Image preview area (item form)
|
|
- Move image from bottom of form to a full-width hero area at the top
|
|
- 4:3 landscape aspect ratio (matches ItemCard's existing aspect-[4/3])
|
|
- When no image: light gray background with centered Lucide icon (ImagePlus or Camera) and "Click to add photo" text below
|
|
- When image exists: full-width image with object-cover, small circular X button in top-right to remove
|
|
- Clicking the image opens file picker to replace (same behavior as clicking placeholder)
|
|
|
|
### Card placeholders
|
|
- All cards (items and candidates) show the 4:3 image area always — consistent card heights in grid
|
|
- When no image: light gray (gray-50/gray-100) background with the item's category icon centered
|
|
- Category icons are currently emoji — use whatever is current (Phase 6 will migrate to Lucide)
|
|
- Candidate cards get the same placeholder treatment as item cards
|
|
|
|
### Upload interaction
|
|
- Click only — no drag-and-drop (keeps it simple for side panel form)
|
|
- Spinner overlay centered on hero area while uploading
|
|
- No client-side image processing (no crop, no resize) — CSS object-cover handles display
|
|
- CandidateForm gets the same hero area redesign as ItemForm
|
|
|
|
### Image in detail/setup views
|
|
- Clicking uploaded image in form opens file picker to replace (no lightbox/zoom)
|
|
- Setup item lists show small square thumbnails (~40px) with rounded corners next to item name
|
|
- Setup thumbnails show category icon placeholder when item has no image
|
|
|
|
### Image display bug fix
|
|
- Investigate and fix root cause of images uploading but not rendering (likely path/proxy issue)
|
|
- This is prerequisite work — fix before redesigning the UX
|
|
|
|
### Claude's Discretion
|
|
- Exact placeholder icon choice (ImagePlus vs Camera vs similar)
|
|
- Spinner animation style
|
|
- Exact gray shade for placeholder backgrounds
|
|
- Transition/animation on image load
|
|
- Error state design for failed uploads
|
|
|
|
</decisions>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `ImageUpload` component (`src/client/components/ImageUpload.tsx`): Existing upload logic with file validation, apiUpload call, preview, and remove button — needs restructuring into hero area pattern
|
|
- `ItemCard` (`src/client/components/ItemCard.tsx`): Already renders imageFilename with `aspect-[4/3]` but skips image area when null — needs placeholder addition
|
|
- `CandidateCard` / `CandidateForm`: Candidate equivalents that need same treatment
|
|
- `apiUpload` helper in `lib/api.ts`: Upload function already works
|
|
|
|
### Established Patterns
|
|
- Images stored as UUID filenames in `./uploads/` directory
|
|
- Server serves `/uploads/*` via `hono/bun` serveStatic
|
|
- Vite dev proxy forwards `/uploads` to `http://localhost:3000`
|
|
- Image upload API at `POST /api/images` returns `{ filename }` (201 status)
|
|
- `imageFilename` field on items and candidates — string or null
|
|
- 5MB max, JPG/PNG/WebP accepted
|
|
|
|
### Integration Points
|
|
- `src/client/components/ItemForm.tsx`: Move ImageUpload from bottom to top, redesign as hero area
|
|
- `src/client/components/CandidateForm.tsx`: Same hero area redesign
|
|
- `src/client/components/ItemCard.tsx`: Add placeholder when imageFilename is null
|
|
- `src/client/components/CandidateCard.tsx`: Add placeholder when imageFilename is null
|
|
- `src/client/routes/setups/$setupId.tsx`: Add small thumbnails to setup item list
|
|
- Server static file serving: Verify `/uploads/*` path works in both dev and production
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Hero area should feel like a product photo section — clean, prominent, image-first
|
|
- Placeholder with category icon adds visual meaning even before images are uploaded
|
|
- Consistent 4:3 aspect ratio across hero area and cards keeps everything aligned
|
|
- Setup thumbnails should be compact (40px square) — don't dominate the list layout
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 05-image-handling*
|
|
*Context gathered: 2026-03-15*
|