<?php
namespace Components\Data\Contracts;

/**
 * Provides contextual add-on actions for modules/cards in BeezUI.
 *
 * Each action item is a simple associative array consumed by UI templates
 * to render buttons or menu entries. Common keys:
 * - label: string        Visible text
 * - icon: string|null    Optional inline SVG
 * - variant: string      Button variant (e.g., 'ghost', 'primary')
 * - size: string         Button size (e.g., 'sm', 'md')
 * - attrs: array         HTML attributes for the trigger element
 */
interface AddonActionsProvider
{
    /**
     * Return add-on actions for a specific module code.
     *
     * @param string $module Module code (e.g., 'winback_advanced')
     * @return array<int, array<string, mixed>>
     */
    public function getActionsForModule(string $module): array;

    /**
     * Optional global (non-module-specific) actions that can be shown in UI
     * toolbars. Implementations may return an empty array if unused.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getGlobalActions(): array;
}
