# Phase 4: Item and Recipient Detail Editing - Context

**Gathered:** 2026-02-27
**Status:** Ready for planning

<domain>
## Phase Boundary

Enable local operational editing for items in possession and latest note updates, plus a floating recipient summary opened from the card. This phase defines editing and summary behavior inside the existing dashboard flow; it does not add new discovery/navigation systems or long-term history browsing features.

</domain>

<decisions>
## Implementation Decisions

### Recipient summary popover behavior
- Opening: recipient name interaction should include a dedicated summary affordance (`name + icon`) instead of name-only text target.
- Placement: summary is a floating panel anchored to the selected card, not a centered modal or permanent side panel.
- Structure: keep concise sections for required CARD-10 fields (all items in possession, last shipment date, products received in last shipment, last status update).
- Dismissal: close via outside click and `Esc`.

### Item add/edit/remove workflow
- Entry point: show inline item action controls when hovering the card's products/items list.
- Add flow: input is name-first, but behaves as fuzzy search over existing reusable item catalog entries and matching Shopify products so pre-defined items (including image metadata) can be reused quickly.
- Shopify-linked items: allow local rename/display-name adjustments; do not allow full structural edits that can drift from upstream linkage.
- Removal: require confirmation, then remove item association from the card/package context without deleting the reusable local item catalog record.

### Latest note editing workflow
- Entry point: notes are edited inline on the card (package context), not on recipient profile surfaces.
- Save semantics: explicit save action (not blur auto-save or per-keystroke persistence).
- Format: multi-line plain text is supported for note content.
- Data target: each card represents a package, so edits commit to that card/package's latest note.

### Claude's Discretion
- Exact iconography, hover reveal animation, and spacing for inline item controls.
- Popover width/height constraints and long-content overflow treatment.
- Exact wording/style for validation and save-success/error feedback.

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `crates/app/ui/dashboard.slint`: current card-grid visual baseline where recipient name, item summary, and note preview already exist; phase 4 can layer hover actions and summary trigger onto this layout.
- `crates/app/src/dashboard/view_model.rs`: note preview and missing-state helpers already normalize/truncate note display for card scan speed.
- `crates/service/src/db/repository.rs`: optimistic-concurrency `upsert_item` and `upsert_package` paths can back edit persistence and conflict handling.

### Established Patterns
- Dashboard state uses per-card runtime flags (`crates/app/src/dashboard/mod.rs`) for transient UI states (selection, refresh, errors), a natural place to track edit-mode/saving/error chips.
- Snapshot projection pipeline (`crates/app/src/dashboard/projection.rs`) maps service snapshots into card view models; edits should round-trip through service snapshot refresh rather than ad hoc UI-only mutation.
- Current service client contract (`crates/app/src/service_client.rs`) supports fetch/refresh only; mutation methods for item/note edits must be added for phase 4.

### Integration Points
- Service API recipient snapshot (`crates/service/src/api/recipients.rs`) is the current source for card fields (`item_summary`, `latest_note`, image hint); phase 4 needs complementary mutation endpoints/commands and snapshot projection updates.
- Core domain + schema (`crates/core/src/domain/item.rs`, `crates/core/src/domain/package.rs`, `crates/service/migrations/0001_initial_schema.sql`) already model item ownership and package latest note, enabling persistence without new top-level entities.

</code_context>

<specifics>
## Specific Ideas

- Inline controls should appear on hover over the card item list, not in separate pages or modals.
- Adding an item should feel like smart lookup first (existing local items + Shopify matches), then new manual entry only when needed.
- Item removal should unassign from the current card/package while preserving reusable item records for future assignment elsewhere.

</specifics>

<deferred>
## Deferred Ideas

- Full note history browsing/timeline per card (beyond editing the current latest note) is a separate capability and should be planned as a future phase.

</deferred>

---

*Phase: 04-item-and-recipient-detail-editing*
*Context gathered: 2026-02-27*