Skip to content

src.tapmap.state.modal

src.tapmap.state.modal

Modal state transition logic.

Provide pure decision functions for closing, opening, and switching modal screens.

ModalRoute dataclass

Describe the next high level modal controller route.

action
  • "apply": apply modal_state (open, switch, or close)
  • "open_data": request opening the GeoIP data folder
  • "noop": no change
modal_state
  • full next modal_state dict, or None to close, used when action == "apply"
Source code in src/tapmap/state/modal.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@dataclass(frozen=True)
class ModalRoute:
    """Describe the next high level modal controller route.

    action:
      - "apply": apply modal_state (open, switch, or close)
      - "open_data": request opening the GeoIP data folder
      - "noop": no change

    modal_state:
      - full next modal_state dict, or None to close, used when action == "apply"
    """

    # action: Literal["apply", "open_data", "noop"]
    action: Literal["apply", "noop"]
    modal_state: dict[str, Any] | None = None

_decide_close(*, trigger, is_open, action)

Return None to close the modal, or no decision if not applicable.

Source code in src/tapmap/state/modal.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def _decide_close(
    *,
    trigger: Any,
    is_open: bool,
    action: Any,
) -> dict[str, Any] | None:
    """Return None to close the modal, or no decision if not applicable."""
    if trigger == "btn_close" and is_open:
        return None

    if trigger == "key_action" and action == "escape" and is_open:
        return None

    return ...  # sentinel meaning "no decision"

_decide_screen_change(*, trigger, is_open, current_screen, show_system, action, menu_screens, open_ports_prefs, now_iso)

Return full modal_state for screen transitions, or None if not applicable.

Source code in src/tapmap/state/modal.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def _decide_screen_change(
    *,
    trigger: Any,
    is_open: bool,
    current_screen: str | None,
    show_system: bool,
    action: Any,
    menu_screens: set[str],
    open_ports_prefs: dict[str, Any] | None,
    now_iso: str,
) -> dict[str, Any] | None:
    """Return full modal_state for screen transitions, or None if not applicable."""
    if trigger == "key_action" and isinstance(action, str) and action in menu_screens:
        screen = action
        payload: dict[str, Any] = {}

        if screen == "menu_open_ports":
            prefs = open_ports_prefs or {}
            payload["show_system"] = bool(prefs.get("show_system", False))

        return {"screen": screen, "t": now_iso, "payload": payload}

    if trigger == "toggle_open_ports_system":
        if not is_open or current_screen != "menu_open_ports":
            return None
        return {"screen": "menu_open_ports", "t": now_iso, "payload": {"show_system": show_system}}

    if trigger in menu_screens:
        screen = str(trigger)
        payload: dict[str, Any] = {}

        if screen == "menu_open_ports":
            prefs = open_ports_prefs or {}
            payload["show_system"] = bool(prefs.get("show_system", False))

        return {"screen": screen, "t": now_iso, "payload": payload}

    return None

_decide_map_click(*, trigger, click_data, now_iso)

Return full modal_state for map click, or None if not applicable.

Source code in src/tapmap/state/modal.py 
86
87
88
89
90
91
92
93
94
95
96
97
98
def _decide_map_click(
    *,
    trigger: Any,
    click_data: Any,
    now_iso: str,
) -> dict[str, Any] | None:
    """Return full modal_state for map click, or None if not applicable."""
    if trigger != "map":
        return None
    if click_data is None:
        return None

    return {"screen": "map_click", "t": now_iso, "payload": {"click_data": click_data}}

_decide_internal_navigation(*, trigger, now_iso)

Return modal_state for internal modal navigation.

Source code in src/tapmap/state/modal.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def _decide_internal_navigation(
    *,
    trigger: Any,
    now_iso: str,
) -> dict[str, Any] | None:
    """Return modal_state for internal modal navigation."""
    if trigger == "btn_view_log":
        return {
            "screen": "menu_insights_log",
            "t": now_iso,
            "payload": {},
        }

    if trigger == "btn_log_back":
        return {
            "screen": "menu_daily_report",
            "t": now_iso,
            "payload": {},
        }

    return None

decide_modal_route(*, trigger, is_open, current_screen, action, show_system, menu_screens, open_ports_prefs, click_data, now_iso)

Decide modal routing in a single priority ordered function.

Source code in src/tapmap/state/modal.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def decide_modal_route(
    *,
    trigger: Any,
    is_open: bool,
    current_screen: str | None,
    action: Any,
    show_system: bool,
    menu_screens: set[str],
    open_ports_prefs: dict[str, Any] | None,
    click_data: Any,
    now_iso: str,
) -> ModalRoute:
    """Decide modal routing in a single priority ordered function."""
    close_result = _decide_close(
        trigger=trigger,
        is_open=is_open,
        action=action,
    )
    if close_result is None:
        return ModalRoute(action="apply", modal_state=None)
    if close_result is not ...:
        # This should never happen, but keeps the contract explicit.
        return ModalRoute(action="noop")

    next_state = _decide_screen_change(
        trigger=trigger,
        is_open=is_open,
        current_screen=current_screen,
        show_system=show_system,
        action=action,
        menu_screens=menu_screens,
        open_ports_prefs=open_ports_prefs,
        now_iso=now_iso,
    )
    if next_state is not None:
        return ModalRoute(action="apply", modal_state=next_state)

    next_state = _decide_internal_navigation(
        trigger=trigger,
        now_iso=now_iso,
    )
    if next_state is not None:
        return ModalRoute(
            action="apply",
            modal_state=next_state,
        )   

    next_state = _decide_map_click(
        trigger=trigger,
        click_data=click_data,
        now_iso=now_iso,
    )
    if next_state is not None:
        return ModalRoute(action="apply", modal_state=next_state)

    return ModalRoute(action="noop")