pythonnative 0.37.0__tar.gz → 0.38.0__tar.gz

{pythonnative-0.37.0/src/pythonnative.egg-info → pythonnative-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.37.0
+Version: 0.38.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -34,16 +34,13 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: User Interfaces
-Requires-Python: >=3.10
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.31.0
-Requires-Dist: tomli>=2.0; python_version < "3.11"
-Requires-Dist: typing_extensions>=4.4; python_version < "3.11"
 Provides-Extra: build
 Requires-Dist: Pillow>=10.0; extra == "build"
 Dynamic: license-file
@@ -86,7 +83,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect` / `use_layout_effect`, refs and imperative handles with `use_ref` / `use_imperative_handle`, and navigation with `use_navigation`, all through one consistent pattern. Components can return a single element, a list of siblings, or `None`, and `Fragment`, `Portal`, and reactive `Provider` context work the way they do in React.
 - **Async-first rendering:** One `asyncio` event loop runs the whole framework on the platform's main thread. Components can be `async def` and `await` data directly in the body; `Suspense` boundaries show declarative loading states while they wait. `use_resource` fetches during render, `use_effect` accepts coroutine callbacks (cancelled automatically on unmount), `lazy` code-splits components, and `use_transition` / `use_deferred_value` keep the UI responsive during expensive updates.
 - **Developer feedback that finds your bugs:** In dev mode (`pn preview`, hot reload, or `PN_DEV=1`), uncaught errors from renders, effects, and event handlers show a full-screen RedBox with the traceback; unknown style keys and duplicate list keys print "did you mean" warnings; and conditional hooks raise a `HookOrderError` at the source instead of silently cross-wiring state.
-- **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
+- **Typed `style` prop and theme:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`, and read design tokens from a typed, immutable `pn.Theme` via `use_theme()` that follows light and dark mode by default.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally**: only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements, so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
 - **Native-driven animations:** The `Animated` API (timing / spring / decay / loop / stagger, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest. `interpolate`, arithmetic operators on animated nodes, `Animated.event` scroll binding, and `diff_clamp` cover the scroll-driven patterns (collapsing headers, parallax) that define native feel.
@@ -95,6 +92,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Native rendering core:** each commit is one serialized transaction applied by Swift and Kotlin component managers, the same shape as React Native's Fabric. Device APIs are native modules registered by name (TurboModules-style), callable from thin Python facades.
 - **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
+- **PyPI packages, binary wheels included:** List requirements in `pythonnative.toml` and the CLI resolves them for the *device* (iOS wheels via PEP 730 and BeeWare's index, Android wheels via PEP 738 and Chaquopy), bundling numpy, Pillow, cryptography, and friends alongside pure-Python packages. `pn deps` reports what each target resolves to before you build, and a weekly-checked compatibility matrix keeps the docs honest.
 - **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect; `use_back_handler` intercepts the back action when a screen needs to.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
@@ -104,6 +102,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 
 ### Installation
 
+Requires Python 3.13 or newer.
+
 ```bash
 pip install pythonnative
 ```

{pythonnative-0.37.0 → pythonnative-0.38.0}/README.md

@@ -36,7 +36,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect` / `use_layout_effect`, refs and imperative handles with `use_ref` / `use_imperative_handle`, and navigation with `use_navigation`, all through one consistent pattern. Components can return a single element, a list of siblings, or `None`, and `Fragment`, `Portal`, and reactive `Provider` context work the way they do in React.
 - **Async-first rendering:** One `asyncio` event loop runs the whole framework on the platform's main thread. Components can be `async def` and `await` data directly in the body; `Suspense` boundaries show declarative loading states while they wait. `use_resource` fetches during render, `use_effect` accepts coroutine callbacks (cancelled automatically on unmount), `lazy` code-splits components, and `use_transition` / `use_deferred_value` keep the UI responsive during expensive updates.
 - **Developer feedback that finds your bugs:** In dev mode (`pn preview`, hot reload, or `PN_DEV=1`), uncaught errors from renders, effects, and event handlers show a full-screen RedBox with the traceback; unknown style keys and duplicate list keys print "did you mean" warnings; and conditional hooks raise a `HookOrderError` at the source instead of silently cross-wiring state.
-- **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
+- **Typed `style` prop and theme:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`, and read design tokens from a typed, immutable `pn.Theme` via `use_theme()` that follows light and dark mode by default.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
 - **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally**: only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements, so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
 - **Native-driven animations:** The `Animated` API (timing / spring / decay / loop / stagger, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest. `interpolate`, arithmetic operators on animated nodes, `Animated.event` scroll binding, and `diff_clamp` cover the scroll-driven patterns (collapsing headers, parallax) that define native feel.
@@ -45,6 +45,7 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 - **Native rendering core:** each commit is one serialized transaction applied by Swift and Kotlin component managers, the same shape as React Native's Fabric. Device APIs are native modules registered by name (TurboModules-style), callable from thin Python facades.
 - **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
+- **PyPI packages, binary wheels included:** List requirements in `pythonnative.toml` and the CLI resolves them for the *device* (iOS wheels via PEP 730 and BeeWare's index, Android wheels via PEP 738 and Chaquopy), bundling numpy, Pillow, cryptography, and friends alongside pure-Python packages. `pn deps` reports what each target resolves to before you build, and a weekly-checked compatibility matrix keeps the docs honest.
 - **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect; `use_back_handler` intercepts the back action when a screen needs to.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
@@ -54,6 +55,8 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 
 ### Installation
 
+Requires Python 3.13 or newer.
+
 ```bash
 pip install pythonnative
 ```

{pythonnative-0.37.0 → pythonnative-0.38.0}/pyproject.toml

@@ -4,13 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.37.0"
+version = "0.38.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
 ]
 readme = "README.md"
-requires-python = ">=3.10"
+# The host interpreter must match the embedded runtime (app.python_version)
+# for device builds, and the embedded runtimes are 3.13 and 3.14: CPython
+# gained official iOS support (PEP 730) and Android support (PEP 738) in
+# 3.13, which is what makes binary wheels from PyPI installable at all.
+requires-python = ">=3.13"
 license = { file = "LICENSE" }
 classifiers = [
   "Development Status :: 2 - Pre-Alpha",
@@ -18,15 +22,12 @@ classifiers = [
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: User Interfaces",
 ]
 dependencies = [
   "requests>=2.31.0",
-  "tomli>=2.0; python_version < '3.11'",
-  "typing_extensions>=4.4; python_version < '3.11'",
 ]
 
 [project.optional-dependencies]
@@ -44,10 +45,10 @@ dev = [
   "pytest>=8.0",
   "pytest-asyncio>=0.23",
   "Pillow>=10.0",
-  # `pn run ios` shells out to `sys.executable -m pip` to vendor the
-  # app's [requirements].packages (project/builder.py), and the test
-  # suite exercises that path. `uv sync` does not seed pip the way
-  # `uv venv --seed` did.
+  # `pn deps` and `pn run ios` shell out to `sys.executable -m pip` to
+  # resolve and vendor the app's [requirements].packages for the device
+  # platform tags (project/deps.py), and the test suite exercises that
+  # path. `uv sync` does not seed pip the way `uv venv --seed` did.
   "pip>=24.0",
 ]
 docs = [
@@ -95,7 +96,7 @@ pythonnative = [
 ]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py313"
 line-length = 120
 extend-exclude = [
   "templates",
@@ -136,10 +137,7 @@ convention = "google"
 
 [tool.black]
 line-length = 120
-target-version = ['py39']
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
+target-version = ['py313']
 
 # ── Semantic Release ────────────────────────────────────────────────
 

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/__init__.py

@@ -62,7 +62,7 @@ Example:
     ```
 """
 
-__version__ = "0.37.0"
+__version__ = "0.38.0"
 
 from . import appearance, diagnostics, gestures, images, runtime, sdk
 from .alerts import Alert
@@ -190,6 +190,7 @@ from .style import (
     AutoCapitalize,
     Color,
     Dimension,
+    Display,
     EdgeInsets,
     FlexDirection,
     FlexWrap,
@@ -198,6 +199,7 @@ from .style import (
     KeyboardType,
     LayoutDirection,
     Overflow,
+    PointerEvents,
     Position,
     ReturnKeyType,
     ScaleType,
@@ -207,6 +209,8 @@ from .style import (
     StyleSheet,
     TextAlign,
     TextDecoration,
+    TextTransform,
+    Theme,
     ThemeContext,
     TransformSpec,
     default_theme,
@@ -314,6 +318,7 @@ __all__ = [
     "DEFAULT_DARK_THEME",
     "DEFAULT_LIGHT_THEME",
     "Dimension",
+    "Display",
     "EdgeInsets",
     "FlexDirection",
     "FlexWrap",
@@ -322,6 +327,7 @@ __all__ = [
     "KeyboardType",
     "LayoutDirection",
     "Overflow",
+    "PointerEvents",
     "Position",
     "ReturnKeyType",
     "ScaleType",
@@ -331,6 +337,8 @@ __all__ = [
     "StyleSheet",
     "TextAlign",
     "TextDecoration",
+    "TextTransform",
+    "Theme",
     "ThemeContext",
     "TransformSpec",
     "default_theme",

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/alerts.py

@@ -56,12 +56,9 @@ async def _present(
     implementation records the call and answers from the queue set by
     [`Alert.set_test_response`][pythonnative.alerts.Alert.set_test_response].
     """
-    try:
-        result = await native_module("Alert").call_async(
-            "present", title=title, message=message, buttons=buttons, style=style
-        )
-    except Exception:
-        return -1
+    result = await native_module("Alert").call_async(
+        "present", title=title, message=message, buttons=buttons, style=style
+    )
     try:
         return int(result)
     except (TypeError, ValueError):
@@ -135,14 +132,9 @@ class Alert:
         [`choose`][pythonnative.alerts.Alert.choose] and ``await``
         the result.
         """
-        try:
-            native_module("Alert").call(
-                "show", title=title, message=message, buttons=[{"label": button, "style": "default"}], style="alert"
-            )
-        except Exception:
-            from . import diagnostics
-
-            diagnostics.swallowed("alerts.Alert.show")
+        native_module("Alert").call(
+            "show", title=title, message=message, buttons=[{"label": button, "style": "default"}], style="alert"
+        )
 
     @staticmethod
     async def confirm(

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/cli/pn.py

@@ -6,6 +6,9 @@ The console script `pn` (declared in `pyproject.toml`) dispatches to:
   ``app/``) into ``./name/``, or into the current directory when no name
   is given.
 - `pn doctor [platform]`: diagnose the local toolchain and config.
+- `pn deps [platform]`: resolve ``[requirements].packages`` for every
+  device target and report which wheels would be used (or why a package
+  can't be installed), without building anything.
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
   with Fast Refresh, the fast inner dev loop, no device required.
 - `pn devices [platform]`: list connected devices, emulators, and
@@ -41,6 +44,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, TextIO
 
 from ..project import builder as builder_mod
+from ..project import deps as deps_mod
 from ..project import devices as devices_mod
 from ..project import doctor as doctor_mod
 from ..project.android import collect_logcat_filters
@@ -54,22 +58,29 @@ HOT_RELOAD_DEV_ROOT = "pythonnative_dev"
 # init
 # ======================================================================
 
-_MAIN_TEMPLATE = """import pythonnative as pn
+_MAIN_TEMPLATE = """from typing import TypedDict
+
+import pythonnative as pn
 
 Stack = pn.create_stack_navigator()
 
 
+class DetailParams(TypedDict):
+    count: int
+
+
 @pn.component
 def HomeScreen():
     count, set_count = pn.use_state(0)
     nav = pn.use_navigation()
+    theme = pn.use_theme()
     return pn.ScrollView(
         pn.Column(
-            pn.Text("Hello from PythonNative!", style={"font_size": 24, "bold": True}),
+            pn.Text("Hello from PythonNative!", style={"font_size": theme.font_size_title, "bold": True}),
             pn.Text(f"Tapped {count} times"),
             pn.Button("Tap me", on_press=lambda: set_count(count + 1)),
-            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", {"count": count})),
-            style={"spacing": 12, "padding": 16, "align_items": "stretch"},
+            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", count=count)),
+            style={"spacing": theme.spacing_large, "padding": 16, "align_items": "stretch"},
         )
     )
 
@@ -77,9 +88,9 @@ def HomeScreen():
 @pn.component
 def DetailScreen():
     nav = pn.use_navigation()
-    params = pn.use_route()
+    route = pn.use_route(DetailParams)
     return pn.Column(
-        pn.Text(f"Detail: count was {params.get('count', 0)}", style={"font_size": 20}),
+        pn.Text(f"Detail: count was {route.params['count']}", style={"font_size": 20}),
         pn.Button("Back", on_press=nav.go_back),
         style={"spacing": 12, "padding": 16},
     )
@@ -89,8 +100,8 @@ def DetailScreen():
 def App():
     return pn.NavigationContainer(
         Stack.Navigator(
-            Stack.Screen("Home", component=HomeScreen, options={"title": "Home"}),
-            Stack.Screen("Detail", component=DetailScreen, options={"title": "Detail"}),
+            Stack.Screen("Home", HomeScreen, title="Home"),
+            Stack.Screen("Detail", DetailScreen, title="Detail"),
         )
     )
 """
@@ -278,6 +289,56 @@ def app_id_command(args: argparse.Namespace) -> None:
     print(config.application_id if args.platform == "android" else config.bundle_id)
 
 
+# ======================================================================
+# deps
+# ======================================================================
+
+
+def deps_command(args: argparse.Namespace) -> None:
+    """Report how ``[requirements].packages`` resolve for each device target.
+
+    Runs pip in its cross-platform dry-run mode once per target (iOS
+    device, iOS Simulator, and one per Android ABI) and prints the
+    wheel each package would use, flagging binary wheels and their
+    source index. Exits non-zero when any target can't be satisfied,
+    so it doubles as a CI gate. ``--json`` emits the same data as a
+    machine-readable document.
+
+    Args:
+        args: Parsed namespace with optional ``platform``, ``json``, and
+            ``python`` (the interpreter to run pip with).
+    """
+    platform: Optional[str] = getattr(args, "platform", None)
+    as_json: bool = getattr(args, "json", False)
+    python: Optional[str] = getattr(args, "python", None)
+
+    config = _load_config_or_exit()
+    targets = deps_mod.targets_for(config, platform)
+    runner = builder_mod.SubprocessRunner()
+    if not as_json and config.requirements:
+        print(
+            f"Resolving {len(config.requirements)} requirement(s) for Python {config.python_version} "
+            f"across {len(targets)} target(s)...\n"
+        )
+    resolutions = deps_mod.resolve_all(config, targets, runner=runner, python=python)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "python_version": config.python_version,
+                    "requirements": list(config.requirements),
+                    "targets": [res.to_dict() for res in resolutions],
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(deps_mod.format_report(resolutions, requirements=config.requirements))
+    if any(not res.ok for res in resolutions):
+        sys.exit(1)
+
+
 # ======================================================================
 # preview
 # ======================================================================
@@ -426,8 +487,18 @@ def run_project(args: argparse.Namespace) -> None:
     config = _load_config_or_exit()
     builder = builder_mod.Builder(config, log=print)
 
+    # Resolve third-party packages only for the destination being built
+    # (device wheels and Simulator wheels differ); prepare-only keeps both
+    # slices so the staged project builds for either in Xcode.
+    if prepare_only:
+        ios_sdks: tuple = deps_mod.IOS_SDKS
+    elif device is not None and device.kind == "device":
+        ios_sdks = ("iphoneos",)
+    else:
+        ios_sdks = ("iphonesimulator",)
+
     try:
-        prepared = builder.prepare(platform)
+        prepared = builder.prepare(platform, ios_sdks=ios_sdks)
     except builder_mod.BuildError as exc:
         print(f"Error: {exc}")
         sys.exit(1)
@@ -593,7 +664,11 @@ def build_project(args: argparse.Namespace) -> None:
         sys.exit(1)
 
     try:
-        prepared = builder.prepare(platform, release=not debug)
+        prepared = builder.prepare(
+            platform,
+            release=not debug,
+            ios_sdks=("iphonesimulator",) if debug else ("iphoneos",),
+        )
         if platform == "android":
             artifacts = builder.build_android(prepared, debug=debug)
         else:
@@ -1020,6 +1095,17 @@ def _build_parser() -> argparse.ArgumentParser:
     parser_doctor.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict checks to a platform")
     parser_doctor.set_defaults(func=doctor_command)
 
+    parser_deps = subparsers.add_parser(
+        "deps", help="Check which wheels [requirements].packages resolve to on each device target"
+    )
+    parser_deps.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict to a platform")
+    parser_deps.add_argument("--json", action="store_true", help="Print a JSON report for scripting")
+    parser_deps.add_argument(
+        "--python",
+        help="Interpreter to run pip with (default: the one running pn; any version works, pip cross-resolves)",
+    )
+    parser_deps.set_defaults(func=deps_command)
+
     parser_preview = subparsers.add_parser("preview", help="Render the app in a desktop window")
     parser_preview.add_argument(
         "component",

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/components/_base.py

@@ -76,6 +76,37 @@ def _make_element(
     return Element(name, out, list(children), key=key)
 
 
+# ======================================================================
+# RefreshControl attachment
+# ======================================================================
+
+REFRESH_CONTROL_TYPE = "RefreshControl"
+"""Element type produced by [`RefreshControl`][pythonnative.RefreshControl]."""
+
+
+def _refresh_control_props(control: Optional[Element], *, owner: str) -> Optional[Dict[str, Any]]:
+    """Turn a ``RefreshControl`` element into the ``refresh_control`` wire prop.
+
+    Scroll containers hold their refresh control as a prop rather than
+    a child (the native side attaches a ``UIRefreshControl`` /
+    ``SwipeRefreshLayout`` to the scroll view itself), so the element
+    is unwrapped here into the flat dict the bridge and the event
+    extractor expect. Keeping it an element on the Python side means
+    users build it like every other piece of UI and get a clear error
+    if they pass the wrong thing.
+
+    Raises:
+        TypeError: If ``control`` is not a ``RefreshControl`` element.
+    """
+    if control is None:
+        return None
+    if not isinstance(control, Element) or control.type != REFRESH_CONTROL_TYPE:
+        raise TypeError(
+            f"{owner}(refresh_control=...) expects pn.RefreshControl(...), got {type(control).__name__}: {control!r}"
+        )
+    return dict(control.props)
+
+
 # ======================================================================
 # Rich text spans
 # ======================================================================

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/components/controls.py

@@ -2,7 +2,7 @@
 
 ``Switch``, ``Slider``, ``ProgressBar``, ``ActivityIndicator``,
 ``Checkbox``, ``SegmentedControl``, ``DatePicker``, ``Picker``, the
-``RefreshControl`` spec helper, and ``StatusBar``.
+``RefreshControl``, and ``StatusBar``.
 """
 
 from typing import Any, Callable, Dict, List, Literal, Optional
@@ -10,7 +10,7 @@ from typing import Any, Callable, Dict, List, Literal, Optional
 from ..element import Element
 from ..hooks import Ref
 from ..style import AccessibilityState, Color, StyleProp
-from ._base import _make_element
+from ._base import REFRESH_CONTROL_TYPE, _make_element
 
 
 def Switch(
@@ -426,13 +426,17 @@ def RefreshControl(
     refreshing: bool = False,
     on_refresh: Optional[Callable[[], Any]] = None,
     tint_color: Optional[Color] = None,
-) -> Dict[str, Any]:
-    """Pull-to-refresh spec for [`ScrollView`][pythonnative.ScrollView] / [`FlatList`][pythonnative.FlatList].
+) -> Element:
+    """Pull-to-refresh control for [`ScrollView`][pythonnative.ScrollView] and the list components.
 
-    Returns a plain dict that should be passed as the
-    ``refresh_control=`` prop. Modeled as a dict (not an
-    [`Element`][pythonnative.Element]) so the host scroll container can
-    hold one without it appearing as a child node.
+    Pass the result as the ``refresh_control=`` prop of a
+    [`ScrollView`][pythonnative.ScrollView],
+    [`FlatList`][pythonnative.FlatList], or
+    [`SectionList`][pythonnative.SectionList]. It is a regular
+    [`Element`][pythonnative.Element] (type ``"RefreshControl"``) built
+    like every other piece of UI; the scroll container attaches it to
+    its native scroll view rather than rendering it as a child, and
+    rejects anything else with a ``TypeError``.
 
     Args:
         refreshing: Drive the spinner's visibility from a use_state
@@ -443,8 +447,7 @@ def RefreshControl(
         tint_color: Color of the spinner.
 
     Returns:
-        Dict suitable for the ``refresh_control`` prop on a scroll
-        container.
+        An [`Element`][pythonnative.Element] of type ``"RefreshControl"``.
 
     Example:
         ```python
@@ -467,12 +470,12 @@ def RefreshControl(
             )
         ```
     """
-    spec: Dict[str, Any] = {"refreshing": bool(refreshing)}
-    if on_refresh is not None:
-        spec["on_refresh"] = on_refresh
-    if tint_color is not None:
-        spec["tint_color"] = tint_color
-    return spec
+    return _make_element(
+        REFRESH_CONTROL_TYPE,
+        refreshing=bool(refreshing),
+        on_refresh=on_refresh,
+        tint_color=tint_color,
+    )
 
 
 def StatusBar(

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/components/layout.py

@@ -12,7 +12,7 @@ from ..component import component
 from ..element import Element
 from ..hooks import Ref, use_keyboard_height, use_safe_area_insets, use_state
 from ..style import AccessibilityState, StyleProp, resolve_style
-from ._base import _make_element
+from ._base import _make_element, _refresh_control_props
 
 
 def View(
@@ -281,7 +281,7 @@ def Spacer(
 
 def ScrollView(
     *children: Element,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     scroll_axis: Optional[Literal["vertical", "horizontal"]] = None,
     on_scroll: Optional[Callable[[Dict[str, float]], None]] = None,
     shows_scroll_indicator: bool = True,
@@ -302,11 +302,8 @@ def ScrollView(
 
     Args:
         *children: Child elements to scroll.
-        refresh_control: Optional pull-to-refresh spec, typically
-            constructed via
-            [`RefreshControl`][pythonnative.RefreshControl]. The dict
-            must have ``refreshing`` (bool) and ``on_refresh``
-            (callable).
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element attached to the scroll view for pull-to-refresh.
         scroll_axis: ``"vertical"`` (default) or ``"horizontal"``.
         on_scroll: Callback invoked with ``{"x": …, "y": …}`` content
             offsets as the user scrolls.
@@ -333,7 +330,7 @@ def ScrollView(
         style=style,
         ref=ref,
         key=key,
-        refresh_control=refresh_control,
+        refresh_control=_refresh_control_props(refresh_control, owner="ScrollView"),
         scroll_axis=scroll_axis,
         on_scroll=on_scroll,
         shows_scroll_indicator=False if shows_scroll_indicator is False else None,

{pythonnative-0.37.0 → pythonnative-0.38.0}/src/pythonnative/components/lists.py

@@ -124,7 +124,7 @@ def _VirtualizedList(
     header: Optional[Element] = None,
     footer: Optional[Element] = None,
     empty: Optional[Element] = None,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     on_end_reached: Optional[Callable[[], Any]] = None,
     on_end_reached_threshold: Optional[float] = None,
     on_viewable_items_changed: Optional[Callable[[List[Dict[str, Any]]], None]] = None,
@@ -464,7 +464,7 @@ def FlatList(
     get_item_height: Optional[Callable[[Any, int], float]] = None,
     estimated_item_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     horizontal: bool = False,
     num_columns: int = 1,
     list_header: Optional[Element] = None,
@@ -509,8 +509,8 @@ def FlatList(
         estimated_item_height: Starting extent estimate for rows whose
             true size isn't known yet (default 44).
         separator_height: Gap below each row, in points.
-        refresh_control: Optional pull-to-refresh spec from
-            [`RefreshControl`][pythonnative.RefreshControl].
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element for pull-to-refresh.
         horizontal: Scroll horizontally (extents become widths).
         num_columns: Render items in a grid of this many columns.
         list_header: Element rendered once before all rows.
@@ -666,7 +666,7 @@ def SectionList(
     estimated_item_height: Optional[float] = None,
     section_header_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     list_header: Optional[Element] = None,
     list_footer: Optional[Element] = None,
     list_empty: Optional[Element] = None,
@@ -699,7 +699,7 @@ def SectionList(
         estimated_item_height: Starting estimate for unmeasured rows.
         section_header_height: Header extent in points, when known.
         separator_height: Gap below each item, in points.
-        refresh_control: Optional pull-to-refresh spec.
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl] element.
         list_header: Element rendered once before everything.
         list_footer: Element rendered once after everything.
         list_empty: Element rendered when there are no sections.