<?php

declare(strict_types=1);

namespace CliqThemes\StoreLocator\Markers;

defined('ABSPATH') || exit;

use CliqThemes\StoreLocator\Models\Store;

/**
 * Decides which map marker a store gets.
 *
 * An implementation may answer the same for every store, or resolve per store
 * and per category, and may answer with a design to render instead of an image.
 * The payload formatter asks this and does not care which is installed.
 */
interface MarkerSource
{
    /**
     * Pre-load whatever answering the next N stores will need.
     *
     * Called once with a whole result page so an implementation that reads rows
     * can do it in a fixed number of queries instead of one per store.
     *
     * @param int[] $storeIds
     */
    public function prefetch(array $storeIds): void;

    /**
     * The marker image for a store: {icon_url, width, height}, or null when the
     * map should draw its provider's default pin.
     *
     * @return array{icon_url: string, width: int, height: int}|null
     */
    public function imageFor(Store $store): ?array;

    /**
     * The id of a design to render as this store's marker, or 0 for none.
     *
     * A design is only reachable when the map is in HTML-marker mode; a source
     * with no designs to offer returns 0 and the image above is used.
     */
    public function designIdFor(Store $store): int;
}
