|
| 1 | +/// A home-screen announcement: a dismissible, tappable nudge shown in the |
| 2 | +/// wallet-home carousel (e.g. "Increase privacy with Payjoin"). |
| 3 | +/// |
| 4 | +/// Announcements are defined in code (compile-time), not persisted — only the |
| 5 | +/// per-user *dismissal* fact is stored (see `DismissedAnnouncements` table). |
| 6 | +/// The user-facing title/description are NOT held here: they map to |
| 7 | +/// localization keys in the presentation layer so `domain/` stays Flutter-free. |
| 8 | +library; |
| 9 | + |
| 10 | +/// Stable identifier for each announcement. The enum *name* is the persistence |
| 11 | +/// key (stored in `dismissed_announcements.announcement_id`) and the l10n key |
| 12 | +/// prefix, so **never rename or reorder existing values** — only append. |
| 13 | +enum AnnouncementId { |
| 14 | + /// Shown once the wallet has transaction history and payjoin is disabled, |
| 15 | + /// inviting the user to enable payjoin for better on-chain privacy. |
| 16 | + payjoinPrivacy, |
| 17 | + |
| 18 | + /// Shown while autoswap is enabled, so the user is aware it's active and can |
| 19 | + /// learn what it does. |
| 20 | + autoswapActive, |
| 21 | +} |
| 22 | + |
| 23 | +/// Visual/semantic tone of an announcement, mapped to theme colors in the UI. |
| 24 | +enum AnnouncementTone { info, warning, success } |
| 25 | + |
| 26 | +/// What tapping the announcement's body does. |
| 27 | +sealed class AnnouncementAction { |
| 28 | + const AnnouncementAction(); |
| 29 | +} |
| 30 | + |
| 31 | +/// Tapping the announcement navigates somewhere. The concrete destination is |
| 32 | +/// resolved in the ui layer (`ui/announcement_navigation.dart`) from the |
| 33 | +/// [Announcement]'s id, so `domain/` never imports another feature's router. |
| 34 | +final class NavigateAction extends AnnouncementAction { |
| 35 | + const NavigateAction(); |
| 36 | +} |
| 37 | + |
| 38 | +/// How re-display works after the user dismisses an announcement. |
| 39 | +sealed class DismissPolicy { |
| 40 | + const DismissPolicy(); |
| 41 | +} |
| 42 | + |
| 43 | +/// Once dismissed, never shown again (until its trigger condition itself |
| 44 | +/// changes — which is decided by the trigger, not this policy). |
| 45 | +final class PermanentDismiss extends DismissPolicy { |
| 46 | + const PermanentDismiss(); |
| 47 | +} |
| 48 | + |
| 49 | +/// Dismissed only temporarily: re-arms (becomes eligible again) once [interval] |
| 50 | +/// has elapsed since the dismissal timestamp. |
| 51 | +final class SnoozeDismiss extends DismissPolicy { |
| 52 | + final Duration interval; |
| 53 | + |
| 54 | + SnoozeDismiss(this.interval) { |
| 55 | + if (interval.inMicroseconds <= 0) { |
| 56 | + throw ArgumentError.value( |
| 57 | + interval, |
| 58 | + 'interval', |
| 59 | + 'snooze interval must be positive', |
| 60 | + ); |
| 61 | + } |
| 62 | + } |
| 63 | +} |
| 64 | + |
| 65 | +/// A rich, self-validating announcement definition. |
| 66 | +/// |
| 67 | +/// Invalid instances are impossible to construct: the id is a closed enum, the |
| 68 | +/// action and policy are sealed, and [priority] is validated in the |
| 69 | +/// constructor. Ordering in the carousel is by ascending [priority]. |
| 70 | +class Announcement { |
| 71 | + final AnnouncementId id; |
| 72 | + |
| 73 | + /// Lower shows first in the carousel. Must be non-negative. |
| 74 | + final int priority; |
| 75 | + |
| 76 | + final AnnouncementTone tone; |
| 77 | + final AnnouncementAction action; |
| 78 | + final DismissPolicy dismissPolicy; |
| 79 | + |
| 80 | + Announcement({ |
| 81 | + required this.id, |
| 82 | + required this.priority, |
| 83 | + required this.tone, |
| 84 | + required this.action, |
| 85 | + required this.dismissPolicy, |
| 86 | + }) { |
| 87 | + if (priority < 0) { |
| 88 | + throw ArgumentError.value(priority, 'priority', 'must be non-negative'); |
| 89 | + } |
| 90 | + } |
| 91 | + |
| 92 | + /// Whether a dismissal recorded at [dismissedAt] still suppresses this |
| 93 | + /// announcement as of [now]. Permanent dismissals always suppress; snooze |
| 94 | + /// dismissals stop suppressing once the interval has elapsed. |
| 95 | + bool isSuppressedBy(DateTime dismissedAt, {required DateTime now}) { |
| 96 | + return switch (dismissPolicy) { |
| 97 | + PermanentDismiss() => true, |
| 98 | + SnoozeDismiss(:final interval) => now.isBefore(dismissedAt.add(interval)), |
| 99 | + }; |
| 100 | + } |
| 101 | +} |
0 commit comments