<?php
namespace Components\Data\Contracts;

interface ConfigStoreProvider
{
    /**
     * Return full config map: module => values
     * @return array<string, array<string, mixed>>
     */
    public function getAllConfigs(): array;

    /**
     * Return module config values (assoc array); [] if none
     * @param string $module
     * @return array<string, mixed>
     */
    public function getModuleConfig(string $module): array;

    /**
     * Persist module config values
     * @param string $module
     * @param array<string, mixed> $values
     */
    public function setModuleConfig(string $module, array $values, bool $processOnlyGivenFields = false): void;

    /**
     * Return full status map derived from module_config: module => 'on'|''
     * @return array<string, string>
     */
    public function getAllStatuses(): array;

    /**
     * Return true if module is ON
     */
    public function isModuleOn(string $module): bool;

    /**
     * Set module status on/off, stored as *_STATUS inside module_config
     */
    public function setModuleStatus(string $module, bool $on): void;

    /**
     * UI open state map: module => bool
     * @return array<string, bool>
     */
    public function getUiOpenMap(): array;

    /**
     * Persist a single module UI open/closed state.
     */
    public function setUiOpenState(string $module, bool $open): void;

    /**
     * Column visibility map: key => bool
     * @return array<string, bool>
     */
    public function getColumnStateMap(): array;

    /**
     * Persist a single column visibility state.
     */
    public function setColumnState(string $key, bool $visible): void;

    /**
     * Return map of dismissed notification IDs: id => bool
     * @return array<string, bool>
     */
    public function getDismissedNotifications(): array;

    /**
     * Persist a notification dismissed state.
     */
    public function setNotificationDismissed(string $id, bool $dismissed): void;
    
    /**
     * Read the saved layout name for a logical list identifier. Defaults to 'stack'.
     */
    public function getListLayout(string $listId): string;
    
    /**
     * Persist the selected layout for the given list identifier (user-scoped).
     */
    public function setListLayout(string $listId, string $layout): void;
    
    /**
     * Read the saved grouped flag for a logical list identifier.
     */
    public function getListGrouped(string $listId, bool $default = true): bool;
    
    /**
     * Persist the grouped flag for the given list identifier (user-scoped).
     */
    public function setListGrouped(string $listId, bool $grouped): void;

    /**
     * Read the saved per-page value for a logical list identifier. Defaults to $default.
     */
    public function getListPerPage(string $listId, int $default = 25): int;

    /**
     * Persist the per-page value for the given list identifier (user-scoped).
     */
    public function setListPerPage(string $listId, int $perPage): void;

    /**
     * Read the full newsletter UI state blob for the current user.
     */
    public function getNewsletterUiState(string $pageMode = ''): array;
    
    /**
     * Merge and persist newsletter UI state fields for the current user.
     */
    public function setNewsletterUiState(array $patch, string $pageMode = ''): void;

    /**
     * Get or create a private feed token for the calendar.
     */
    public function getCalendarFeedToken(): string;

    /**
     * Generate a new private feed token for the calendar.
     */
    public function rotateCalendarFeedToken(): string;

    /**
     * Optional: list known config keys for a module
     * @return array<int, string>
     */
    public function listKeys(string $module): array;

    /**
     * Return true if the module configuration has been saved at least once.
     */
    public function isConfigured(string $module): bool;

    /**
     * Mark the module as configured.
     */
    public function setConfigured(string $module): void;

    /**
     * Clear the configured marker for the given module (e.g., on uninstall).
     */
    public function clearConfigured(string $module): void;

    /**
     * Read the saved view mode (journey|performance) for a logical view identifier.
     */
    public function getViewMode(string $viewId, string $default = 'journey'): string;

    /**
     * Persist the selected view mode for the given view identifier (user-scoped).
     */
    public function setViewMode(string $viewId, string $mode): void;

    /**
     * Read the saved performance timeframe for a logical view identifier.
     */
    public function getPerformanceTimeframe(string $context, string $default = '30days'): string;

    /**
     * Persist the selected performance timeframe for the given view identifier (user-scoped).
     */
    public function setPerformanceTimeframe(string $context, string $timeframe): void;
}
