pythonnative 0.22.1__py3-none-any.whl → 0.24.0__py3-none-any.whl

pythonnative/navigation.py

@@ -45,11 +45,12 @@ Example:
     ```
 """
 
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, TypedDict, Union
 
 from .element import Element
 from .hooks import (
     Provider,
+    Ref,
     _NavigationContext,
     component,
     create_context,
@@ -60,6 +61,29 @@ from .hooks import (
     use_state,
 )
 
+
+class ScreenOptions(TypedDict, total=False):
+    """Typed per-screen options accepted by ``Screen(..., options=...)``.
+
+    All keys are optional. Navigators ignore keys they don't use.
+
+    Attributes:
+        title: Human-readable screen title. Stack navigators forward it
+            to the host's native navigation bar; tab and drawer
+            navigators use it as the item label.
+        tab_bar_icon: Native system icon identifier for tab items. A
+            string is used on every platform; a dict like
+            ``{"ios": "house.fill", "android": "ic_menu_home"}``
+            selects per platform. iOS values are resolved via
+            SF Symbols (``UIImage.systemImageNamed_``); Android values
+            are resolved against ``android.R.drawable.<name>``. Names
+            that don't resolve fall back to text-only.
+    """
+
+    title: str
+    tab_bar_icon: Union[str, Dict[str, str]]
+
+
 # ======================================================================
 # Focus context
 # ======================================================================
@@ -85,14 +109,14 @@ class _ScreenDef:
         name: Route name used by `navigate(name, ...)`.
         component: A `@component` function rendered when this screen is
             active.
-        options: Free-form per-screen options (e.g., `title` for the
-            tab bar, `headerShown`, etc.). Interpretation is up to the
-            specific navigator implementation.
+        options: Per-screen [`ScreenOptions`][pythonnative.ScreenOptions]
+            (e.g., `title`, `tab_bar_icon`). Interpretation is up to
+            the specific navigator implementation.
     """
 
     __slots__ = ("name", "component", "options")
 
-    def __init__(self, name: str, component_fn: Any, options: Optional[Dict[str, Any]] = None) -> None:
+    def __init__(self, name: str, component_fn: Any, options: Optional[ScreenOptions] = None) -> None:
         self.name = name
         self.component = component_fn
         self.options = options or {}
@@ -450,10 +474,10 @@ def _stack_navigator_impl(screens: Any = None, initial_route: Optional[str] = No
     stack, set_stack = use_state(lambda: [_RouteEntry(first_route, first_params)])
 
     stack_ref = use_ref(None)
-    stack_ref["current"] = stack
+    stack_ref.current = stack
 
     handle = use_memo(
-        lambda: _DeclarativeNavHandle(screen_map, lambda: stack_ref["current"], set_stack, parent=parent_nav), []
+        lambda: _DeclarativeNavHandle(screen_map, lambda: stack_ref.current, set_stack, parent=parent_nav), []
     )
     handle._screen_map = screen_map
     handle._parent = parent_nav
@@ -505,7 +529,7 @@ def create_stack_navigator() -> Any:
 
     class _StackNavigator:
         @staticmethod
-        def Screen(name: str, *, component: Any, options: Optional[Dict[str, Any]] = None) -> "_ScreenDef":
+        def Screen(name: str, *, component: Any, options: Optional[ScreenOptions] = None) -> "_ScreenDef":
             """Define a screen within this stack navigator.
 
             Args:
@@ -556,8 +580,8 @@ def _tab_navigator_impl(screens: Any = None, initial_route: Optional[str] = None
     active_tab, set_active_tab = use_state(first_route)
     tab_params, set_tab_params = use_state(lambda: {first_route: {}})
 
-    params_ref = use_ref(None)
-    params_ref["current"] = tab_params
+    params_ref: Ref[Dict[str, Dict[str, Any]]] = use_ref(None)
+    params_ref.current = tab_params
 
     def switch_tab(name: str, params: Optional[Dict[str, Any]] = None) -> None:
         set_active_tab(name)
@@ -565,7 +589,7 @@ def _tab_navigator_impl(screens: Any = None, initial_route: Optional[str] = None
             set_tab_params(lambda p: {**p, name: params})
 
     def get_stack() -> List[_RouteEntry]:
-        p = params_ref["current"] or {}
+        p = params_ref.current or {}
         return [_RouteEntry(active_tab, p.get(active_tab, {}))]
 
     handle = use_memo(lambda: _TabNavHandle(screen_map, get_stack, lambda _: None, switch_tab, parent=parent_nav), [])
@@ -643,7 +667,7 @@ def create_tab_navigator() -> Any:
 
     class _TabNavigator:
         @staticmethod
-        def Screen(name: str, *, component: Any, options: Optional[Dict[str, Any]] = None) -> "_ScreenDef":
+        def Screen(name: str, *, component: Any, options: Optional[ScreenOptions] = None) -> "_ScreenDef":
             """Define a screen within this tab navigator.
 
             Args:
@@ -704,8 +728,8 @@ def _drawer_navigator_impl(screens: Any = None, initial_route: Optional[str] = N
     drawer_open, set_drawer_open = use_state(False)
     screen_params, set_screen_params = use_state(lambda: {first_route: {}})
 
-    params_ref = use_ref(None)
-    params_ref["current"] = screen_params
+    params_ref: Ref[Dict[str, Dict[str, Any]]] = use_ref(None)
+    params_ref.current = screen_params
 
     def switch_screen(name: str, params: Optional[Dict[str, Any]] = None) -> None:
         set_active_screen(name)
@@ -713,7 +737,7 @@ def _drawer_navigator_impl(screens: Any = None, initial_route: Optional[str] = N
             set_screen_params(lambda p: {**p, name: params})
 
     def get_stack() -> List[_RouteEntry]:
-        p = params_ref["current"] or {}
+        p = params_ref.current or {}
         return [_RouteEntry(active_screen, p.get(active_screen, {}))]
 
     handle = use_memo(
@@ -763,7 +787,7 @@ def _drawer_navigator_impl(screens: Any = None, initial_route: Optional[str] = N
                 return _select
 
             menu_items.append(
-                Element("Button", {"title": label, "on_click": make_select(item_name)}, [], key=f"__drawer_{item_name}")
+                Element("Button", {"title": label, "on_press": make_select(item_name)}, [], key=f"__drawer_{item_name}")
             )
 
         drawer_panel = Element(
@@ -813,7 +837,7 @@ def create_drawer_navigator() -> Any:
 
     class _DrawerNavigator:
         @staticmethod
-        def Screen(name: str, *, component: Any, options: Optional[Dict[str, Any]] = None) -> "_ScreenDef":
+        def Screen(name: str, *, component: Any, options: Optional[ScreenOptions] = None) -> "_ScreenDef":
             """Define a screen within this drawer navigator.
 
             Args:

pythonnative/preview.py

@@ -43,6 +43,36 @@ _POLL_INTERVAL_MS = 16
 _WATCH_INTERVAL_S = 0.4
 
 
+def _publish_desktop_color_scheme() -> None:
+    """Publish the host OS appearance so `use_color_scheme` works in preview.
+
+    ``PN_COLOR_SCHEME=light|dark`` forces a value (handy for testing
+    both appearances); otherwise macOS is asked via ``defaults read``
+    (the key only exists when dark mode is on). Other platforms default
+    to light.
+    """
+    from . import appearance
+
+    forced = os.environ.get("PN_COLOR_SCHEME")
+    if forced in ("light", "dark"):
+        appearance.set_system_color_scheme(forced)
+        return
+    if sys.platform == "darwin":
+        import subprocess
+
+        try:
+            result = subprocess.run(
+                ["defaults", "read", "-g", "AppleInterfaceStyle"],
+                capture_output=True,
+                text=True,
+                timeout=2,
+            )
+            is_dark = result.returncode == 0 and result.stdout.strip() == "Dark"
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+
 class DesktopApp:
     """Navigation-stack controller for the desktop preview window.
 
@@ -201,17 +231,13 @@ class DesktopApp:
             host.on_pause()
         except Exception:
             pass
+        # ``on_destroy`` unmounts the host's reconciler: effect cleanups
+        # run, native widgets are destroyed, and event registrations are
+        # released (see ``screen._destroy_host``).
         try:
             host.on_destroy()
         except Exception:
             pass
-        reconciler = getattr(host, "_reconciler", None)
-        tree = getattr(reconciler, "_tree", None) if reconciler is not None else None
-        if reconciler is not None and tree is not None:
-            try:
-                reconciler._destroy_tree(tree)
-            except Exception:
-                pass
         container = getattr(host, "_pn_container", None)
         if container is not None:
             try:
@@ -219,6 +245,29 @@ class DesktopApp:
             except Exception:
                 pass
 
+    def teardown_all(self) -> None:
+        """Destroy every screen on the stack (preview window closing)."""
+        while self._stack:
+            self._teardown(self._stack.pop())
+
+    def back_pressed(self) -> None:
+        """Route a desktop back gesture (Escape) like a hardware back press.
+
+        ``use_back_handler`` subscribers on the active screen get the
+        first chance to consume the event; otherwise the stack pops
+        (matching Android's default back behavior). At the root the
+        event is ignored.
+        """
+        host = self.active_host()
+        if host is None:
+            return
+        try:
+            if host.on_back_pressed():
+                return
+        except Exception:
+            pass
+        self.pop_screen()
+
     # -- viewport / resize --------------------------------------------
 
     def resize(self, width: float, height: float) -> None:
@@ -359,6 +408,13 @@ def run_preview(
         )
 
     root_dir, watched = _resolve_paths(component_path, project_root, watch_dir)
+    _publish_desktop_color_scheme()
+
+    # The preview is inherently a development surface: turn on dev
+    # diagnostics (validation warnings, hook-order checks, RedBox).
+    from . import diagnostics
+
+    diagnostics.set_dev_mode(True)
 
     root = tk.Tk()
     root.title(title)
@@ -383,6 +439,11 @@ def run_preview(
 
     stage.bind("<Configure>", _on_configure)
 
+    # Escape acts as the desktop stand-in for the hardware back button:
+    # ``use_back_handler`` subscribers can intercept it, and otherwise
+    # the navigation stack pops.
+    root.bind("<Escape>", lambda _event: app.back_pressed())
+
     watcher = _build_watcher(watched, root_dir, app, main_queue) if hot_reload else None
     if watcher is not None:
         watcher.start()
@@ -415,6 +476,12 @@ def run_preview(
                 watcher.stop()
             except Exception:
                 pass
+        # Unmount every screen first so effect cleanups (timers, tasks,
+        # subscriptions) run before the Tk interpreter goes away.
+        try:
+            app.teardown_all()
+        except Exception:
+            pass
         runtime_module.set_desktop_main_dispatch(None)
         desktop_backend.clear_root_container()
         try:

pythonnative/project/config.py

@@ -321,15 +321,7 @@ class AppConfig:
         root = Path(project_root) if project_root is not None else Path.cwd()
         config_path = root / CONFIG_FILENAME
         if not config_path.is_file():
-            legacy = root / "pythonnative.json"
-            hint = ""
-            if legacy.is_file():
-                hint = (
-                    "\nFound a legacy 'pythonnative.json'. PythonNative now uses "
-                    "'pythonnative.toml'.\nRun 'pn init --force' to scaffold one, then "
-                    "port your settings over."
-                )
-            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.{hint}")
+            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.")
         try:
             with open(config_path, "rb") as handle:
                 data = _toml.load(handle)