---
# requirements.md

## Purpose
Enhance the [ACF Image Mapping Hotspots](https://wordpress.org/plugins/acf-image-mapping-hotspots/) plugin to support linking hotspots to WordPress posts via a visual selector. This adds flexibility and structured linking to content-rich image maps.

---

## Features

### 🔗 Post Link Support
- Add `post_id` field to each hotspot
- Replace or supplement `text` field with post reference
- Save `post_id` instead of text (or alongside)

### 🖱️ Admin UI Enhancements
- In the hotspot popup:
    - Add a searchable dropdown or input to select a WordPress post
    - Show selected post title in UI
    - Store selected post's ID

### 🧩 Data Structure
- Hotspots saved as JSON objects in a stringified array (status quo)
- Example:
```json
[
  { "x": 30.5, "y": 62.1, "post_id": 253, "label": "Sessel" }
]
```

### 💾 Backend Enhancements
- Sanitize & validate `post_id` field
- Update save/load logic

### 🌐 Frontend Rendering
- Retrieve linked post data (`get_the_title()`, `get_permalink()`)
- Output clickable hotspots with correct link & label

### 🧪 Optional Future Enhancements
- Tooltip with featured image
- ACF Relationship UI integration
- Fallback for deleted post

---

# Compatibility
- WordPress >= 5.5
- ACF >= 5.x
- Plugin: [ACF Image Mapping Hotspots](https://wordpress.org/plugins/acf-image-mapping-hotspots/)

---

# Output Format
Each hotspot entry should be structured as:
```json
{
  "x": 12.5,
  "y": 34.6,
  "post_id": 789
}
```

---
# todos.md

## Phase 1: Setup & Exploration
- [ ] Clone or fork `acf-image-mapping-hotspots` plugin from WordPress.org or GitHub
- [ ] Review current JS logic (`assets/js/admin.js`)
- [ ] Review field PHP logic (`includes/field.php`)

## Phase 2: Add Post Selection UI
- [ ] Modify the hotspot modal to include a post selector input (e.g., text + datalist or AJAX-powered search)
- [ ] Append selected post ID to hotspot object as `post_id`
- [ ] Store `post_id` in JSON structure

## Phase 3: Update Backend Logic
- [ ] Validate and sanitize `post_id` before save
- [ ] Adjust field loading logic to include `post_id`

## Phase 4: Render Linked Posts in Frontend
- [ ] Update `the_field()` render logic or shortcode output
- [ ] Use `get_the_title()` and `get_permalink()` from stored `post_id`

## Phase 5: Polish & Extend
- [ ] Add fallback label for missing post
- [ ] Make text field optional if `post_id` is present
- [ ] Optional: implement post preview tooltip

## Phase 6: Documentation & Contribution
- [ ] Add usage example in plugin readme
- [ ] Write PR or prepare fork for WordPress.org