Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Dashboard\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Engine\Domain\Model\PermissionContext;
12
13/**
14 * Contract for Dashboard Widgets Service.
15 *
16 * @package App\Modules\Dashboard\Application\Service
17 */
18interface DashboardWidgetsServiceInterface
19{
20    public const string WIDGET_CURRENT = 'current_calendar_events';
21    public const string WIDGET_OVERDUE = 'overdue_calendar_events';
22
23    /**
24     * Returns current ongoing or upcoming calendar events.
25     *
26     * @param PermissionContext $context Security permission context.
27     * @param int               $limit   Maximum records to return.
28     * @return array<int, array<string, mixed>> List of current events.
29     */
30    public function getCurrentCalendarEvents(PermissionContext $context, int $limit = 5): array;
31
32    /**
33     * Returns total count of current ongoing or upcoming calendar events.
34     *
35     * @param PermissionContext $context Security permission context.
36     * @return int Total count of upcoming calendar events.
37     */
38    public function getCurrentCalendarEventsCount(PermissionContext $context): int;
39
40    /**
41     * Returns overdue calendar events requiring immediate attention.
42     *
43     * @param PermissionContext $context Security permission context.
44     * @param int               $limit   Maximum records to return.
45     * @return array<int, array<string, mixed>> List of overdue events.
46     */
47    public function getOverdueCalendarEvents(PermissionContext $context, int $limit = 5): array;
48
49    /**
50     * Returns total count of overdue calendar events requiring immediate attention.
51     *
52     * @param PermissionContext $context Security permission context.
53     * @return int Total count of overdue calendar events.
54     */
55    public function getOverdueCalendarEventsCount(PermissionContext $context): int;
56
57    /**
58     * Returns list of all available widgets with active status for the given user.
59     *
60     * @param int               $userId  User record ID.
61     * @param PermissionContext $context Security context.
62     * @return array<string, array<string, mixed>> Map of widget definitions.
63     */
64    public function getAvailableWidgets(int $userId, PermissionContext $context): array;
65
66    /**
67     * Returns inactive widgets available to be restored by the user.
68     *
69     * @param int               $userId  User record ID.
70     * @param PermissionContext $context Security context.
71     * @return array<int, array<string, mixed>> List of inactive widget metadata.
72     */
73    public function getInactiveWidgets(int $userId, PermissionContext $context): array;
74
75    /**
76     * Returns array of active widget names for user.
77     *
78     * @param int $userId User record ID.
79     * @return array<int, string> Active widget keys.
80     */
81    public function getActiveWidgetKeys(int $userId): array;
82
83    /**
84     * Toggles visibility of a specific widget for user and saves preference.
85     *
86     * @param int    $userId    User record ID.
87     * @param string $widgetKey Widget identifier.
88     * @param bool   $enable    True to activate, false to hide.
89     * @return array<int, string> Updated active widget keys.
90     */
91    public function toggleWidget(int $userId, string $widgetKey, bool $enable): array;
92
93    /**
94     * Checks whether calendar features and widgets are active for the deployment profile.
95     *
96     * @return bool True if calendar module/table is available and profile is client.
97     */
98    public function isCalendarAvailable(): bool;
99}