<?php

declare(strict_types=1);

namespace CliqThemes\StoreLocator\Layouts;

defined('ABSPATH') || exit;

/**
 * Where a locator layout comes from.
 *
 * A locator is rendered from a layout: a widget grid plus the designs it
 * references. One may be assembled from the site's settings, or saved and
 * edited by an author. Everything that renders or lists a locator depends on
 * this, never on a particular supplier.
 *
 * @see LocatorLayouts::source() the resolved implementation
 */
interface LocatorLayoutSource
{
    /**
     * Every layout that can be chosen, in the order it should be offered.
     *
     * @return array<int, array{id: int, name: string}>
     */
    public function all(): array;

    /**
     * One layout as a render payload — {id, name, model, designs} — or null when
     * no layout has that id.
     *
     * @return array<string, mixed>|null
     */
    public function find(int $id): ?array;

    /**
     * The layout a placement renders when it names none.
     *
     * Zero means the site has none: callers should treat that as "ask the
     * author to choose", not as an error.
     */
    public function defaultId(): int;

    /**
     * The model for a single store's own page, or null when there is none.
     *
     * The same question as the rest of this interface, asked about a different
     * surface.
     *
     * @return array<string, mixed>|null a model with a `rows` key
     */
    public function detailModel(): ?array;
}
