Image Hotspots

Image Hotspots places labelled, keyboard-operable markers over one site-owned Media library image. Marker positions are stored as percentages, so they remain attached to the same point when the image scales from a phone to a wide desktop.

Build a hotspot image

1. Upload the image to the selected website's Media library.
2. Choose that managed asset in the widget editor. Direct or remote image URLs are not accepted.
3. Provide meaningful alternative text that describes the complete image. A hotspot image cannot be marked decorative.
4. Add up to 50 hotspots. Give every hotspot a unique stable key, horizontal and vertical percentage coordinates, an accessible label, and a plain-text description.
5. Optionally add a same-site relative link such as /products/example, or a fully qualified HTTPS link.

The Product Tour and Accessible Image Map templates provide safe example content and normalized coordinates. They intentionally do not select an image: the operator must choose a site-owned asset before the public widget displays.

Interaction and accessibility

Each marker is a native button with an accessible label. Tab reaches every marker; arrow keys, Home, and End move between markers. Enter, Space, pointer, and touch activation open a normal-flow detail panel. The detail panel receives focus, keeps Tab within its controls, closes with its close button, Escape, or an outside pointer action, and restores focus to the marker.

Details remain below the responsive image rather than becoming an unbounded floating popover. This keeps long descriptions and links inside the widget and viewport. The marker target is at least 44 by 44 pixels. Motion is limited to a small hover treatment and is disabled when the visitor requests reduced motion.

Content and security boundaries

• Coordinates are finite numbers, clamped to 0–100, rounded to two decimal places, and stored independent of rendered pixels.
• Hotspot keys must be unique and match the stable-key format. Malformed rows, duplicate keys, unknown fields, unsafe links, excessive row counts, overlong text, and oversized serialized content are rejected.
• Labels are limited to 120 characters; descriptions to 1,000; links to 2,048; and a widget to 50 hotspots.
• Hotspot descriptions are plain text and escaped. Optional destinations allow only internal relative references or HTTPS URLs without embedded credentials. External HTTPS links open with noopener noreferrer.
• Media resolution is schema-declared and site-scoped. The saved widget contains the managed asset identity, not a fetched remote image. Existing draft authorization, CSRF, website ownership, transaction, immutable revision/snapshot, media-dependency, and audit-log paths remain authoritative.
• Structured JSON and CSV transfers preserve the hotspot rows and canonical managed-media reference. Moving that reference to another website does not copy the media bytes; move or import the corresponding Media library asset separately before publishing there.
• The public runtime is dependency-free JavaScript. Node is used only by the browser test suite and is not required in production.

Empty and failure states

The renderer shows an honest setup message until a valid managed asset has resolved to a public URL with non-empty alternative text. Corrupt hotspot data fails closed rather than emitting unsafe controls. An unavailable media revision remains governed by the existing Media library dependency and resolution behavior.

Verification

Focused PHP tests cover definition, editor, normalization bounds, duplicates, malformed input, managed-media enforcement, safe links, escaping, and empty rendering. The production browser fixture exercises real registry, renderer, stylesheet, and embed-runtime paths at 390, 768, and 1440 pixels, including coordinate alignment, keyboard control, focus restoration, outside dismissal, reduced motion, remount cleanup, and automated accessibility checks.