pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/reconciler/layout_pass.py

@@ -0,0 +1,393 @@
+"""The layout phase of a reconciler pass.
+
+After native mutations commit, the reconciler builds a
+[`LayoutNode`][pythonnative.layout.LayoutNode] tree mirroring the
+native nodes of the mounted tree, runs the flexbox engine against the
+viewport, and emits a ``SetFrameOp`` for every frame that changed.
+
+Two details keep this cheap on every state update:
+
+- **Incremental rebuild.** Each native ``VNode`` caches its
+  ``LayoutNode``; subtrees whose props and child list are unchanged
+  reuse the cached node with ``dirty=False`` so the engine can serve
+  their sizes from its measurement memo.
+- **Frame diffing.** Frames equal to the last applied frame produce no
+  op at all.
+
+Detached subtrees (``Modal``, ``Portal``) are excluded from the main
+flow and laid out against the viewport as independent trees, since
+their content lives in a separately presented native container.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple
+
+from .. import diagnostics
+from ..element import Element
+from ..layout import LAYOUT_STYLE_KEYS, LayoutNode, calculate_layout, extract_layout_style
+from ..mutations import Mutation, SetFrameOp
+from ..profiling import profiled
+from .vnode import DETACHED_TYPES, VNode
+
+if TYPE_CHECKING:
+    pass
+
+Frame = Tuple[float, float, float, float]
+
+# Native leaves whose size derives from their content; any prop change
+# invalidates their measurement.
+INTRINSIC_TYPES = frozenset(
+    {
+        "Text",
+        "Button",
+        "Image",
+        "TextInput",
+        "Switch",
+        "Slider",
+        "ProgressBar",
+        "ActivityIndicator",
+        "TabBar",
+        "Picker",
+        "Checkbox",
+        "SegmentedControl",
+        "DatePicker",
+    }
+)
+
+# Childless native leaves that get a measure callback. Extends the
+# intrinsic set with ``VirtualList``, whose handlers report "fill the
+# available space" (like a ScrollView clamped to its parent): without
+# the callback an unstyled list would collapse to 0 points and the
+# platform virtualizer would never bind a row.
+MEASURED_LEAF_TYPES = INTRINSIC_TYPES | {"VirtualList"}
+
+
+def affects_layout(type_name: str, changed: Dict[str, Any]) -> bool:
+    """Whether ``changed`` props can alter a native node's layout."""
+    from ..sdk.schema import COMPONENTS
+
+    schema = COMPONENTS.get(type_name)
+    if schema is None or schema.measurement == "intrinsic":
+        return True
+    if any(schema.props.get(key, {}).get("native", {}).get("invalidates_layout") for key in changed):
+        return True
+    return any(key in LAYOUT_STYLE_KEYS for key in changed)
+
+
+class LayoutMixin:
+    """Layout-pass behavior mixed into the reconciler."""
+
+    # Provided by the concrete reconciler.
+    backend: Any
+    root: Optional[VNode]
+    _ops: List[Mutation]
+
+    def _init_layout_state(self) -> None:
+        self._viewport_size: Tuple[float, float] = (0.0, 0.0)
+        self._layout_pass_count = 0
+        # ``(tag, frame)`` pairs whose ``on_layout`` should fire after
+        # the layout pass commits (frames are only queued on change).
+        self._pending_layout_events: List[Tuple[int, Frame]] = []
+
+    # ------------------------------------------------------------------
+    # Public surface
+    # ------------------------------------------------------------------
+
+    @property
+    def viewport_size(self) -> Tuple[float, float]:
+        """The last viewport size supplied by the host, ``(0, 0)`` before layout is possible."""
+        return self._viewport_size
+
+    def set_viewport_size(self, width: float, height: float) -> None:
+        """Update the viewport size and re-run layout if it changed.
+
+        Called by the screen host whenever the platform reports a new
+        container size. The first call after mount triggers the
+        initial layout pass; identical sizes are no-ops.
+        """
+        if width <= 0 or height <= 0:
+            return
+        if self._viewport_size == (width, height):
+            return
+        self._viewport_size = (width, height)
+        if self.root is not None:
+            self._run_layout()
+            self._flush_ops()
+            self._dispatch_layout_events()
+
+    def compute_layout_for_test(self, viewport_width: float, viewport_height: float) -> Optional[LayoutNode]:
+        """Build and compute a layout tree without touching the backend.
+
+        Returns the synthetic viewport ``LayoutNode`` with all
+        descendants positioned, or ``None`` if nothing is mounted.
+        """
+        if self.root is None:
+            return None
+        roots = self._build_layout_list(self.root)
+        if not roots:
+            return None
+        viewport = LayoutNode(style={"width": viewport_width, "height": viewport_height}, children=list(roots))
+        calculate_layout(viewport, viewport_width, viewport_height)
+        return viewport
+
+    # ------------------------------------------------------------------
+    # Hooks used by the core
+    # ------------------------------------------------------------------
+
+    def _flush_ops(self) -> None: ...  # pragma: no cover
+
+    @staticmethod
+    def _mark_layout_dirty(node: VNode) -> None:
+        node.layout_dirty = True
+        node.layout_node = None
+
+    # ------------------------------------------------------------------
+    # The pass
+    # ------------------------------------------------------------------
+
+    @profiled("layout")
+    def _run_layout(self) -> None:
+        """Build/refresh the layout tree, compute frames, and emit changed ones.
+
+        Wraps the user's native roots in a synthetic outer ``LayoutNode``
+        sized to the viewport so the root fills the screen by default.
+        Skipped until the host has supplied a viewport size.
+
+        The first native root's own frame is intentionally left alone:
+        its position and size are owned by the screen host (iOS places
+        it below the safe-area inset; Android attaches it with
+        ``MATCH_PARENT``).
+        """
+        root = self.root
+        if root is None:
+            return
+        viewport_w, viewport_h = self._viewport_size
+        if viewport_w <= 0 or viewport_h <= 0:
+            return
+
+        self._layout_pass_count += 1
+        if getattr(self.backend, "native_layout", False):
+            self.backend.compute_layout([node.tag for node in self._native_roots(root)], viewport_w, viewport_h)
+            return
+        layout_roots = self._build_layout_list_cached(root)
+        if layout_roots:
+            viewport = LayoutNode(style={"width": viewport_w, "height": viewport_h}, children=list(layout_roots))
+            viewport.dirty = True
+            calculate_layout(viewport, viewport_w, viewport_h)
+            for i, layout_root in enumerate(layout_roots):
+                if i == 0:
+                    for child in layout_root.children:
+                        self._collect_frames(child, 0.0, 0.0)
+                else:
+                    self._collect_frames(layout_root, 0.0, 0.0)
+        self._layout_detached_subtrees(root, viewport_w, viewport_h)
+        self._clear_layout_dirty(root)
+
+    def _accept_native_layout(self, frames: list[list[float]]) -> None:
+        """Update refs and queue observations only for acknowledged native frames."""
+        for tag, x, y, width, height in frames:
+            node = self._tag_nodes.get(int(tag))
+            if node is None or not node.mounted:
+                continue
+            frame = (x, y, width, height)
+            node.last_frame = frame
+            ref = node.element.props.get("ref")
+            if ref is not None:
+                ref._pn_frame = frame
+            if "on_layout" in node.element.props:
+                self._pending_layout_events.append((int(tag), frame))
+        if not self._rendering:
+            self._dispatch_layout_events()
+
+    def _layout_detached_subtrees(self, node: VNode, viewport_w: float, viewport_h: float) -> None:
+        element = node.element
+        if isinstance(element.type, str) and element.type in DETACHED_TYPES:
+            active = bool(element.props.get("visible")) if element.type == "Modal" else True
+            if not active:
+                return
+            child_layouts: List[LayoutNode] = []
+            for child in node.children:
+                child_layouts.extend(self._build_layout_list(child))
+            if child_layouts:
+                viewport = LayoutNode(style={"width": viewport_w, "height": viewport_h}, children=child_layouts)
+                calculate_layout(viewport, viewport_w, viewport_h)
+                for c in viewport.children:
+                    self._collect_frames(c, 0.0, 0.0)
+            for child in node.children:
+                self._layout_detached_subtrees(child, viewport_w, viewport_h)
+            return
+        for child in node.children:
+            self._layout_detached_subtrees(child, viewport_w, viewport_h)
+
+    def _build_layout_list_cached(self, node: VNode) -> List[LayoutNode]:
+        """Like ``_build_layout_list`` but reuses cached subtrees when clean."""
+        element = node.element
+        if not node.is_native:
+            out: List[LayoutNode] = []
+            for child in node.children:
+                out.extend(self._build_layout_list_cached(child))
+            return out
+        if element.type in DETACHED_TYPES:
+            return []
+
+        child_layouts: List[LayoutNode] = []
+        for child in node.children:
+            child_layouts.extend(self._build_layout_list_cached(child))
+
+        cached = node.layout_node
+        if cached is not None and not node.layout_dirty:
+            cached_children = self._direct_child_layouts(cached, element)
+            if len(cached_children) == len(child_layouts) and all(
+                a is b for a, b in zip(cached_children, child_layouts)
+            ):
+                return [cached]
+
+        layout = self._new_layout_node(node)
+        for child_layout in child_layouts:
+            if element.type == "ScrollView":
+                child_layout = self._wrap_scroll_axis(child_layout, self._scroll_axis(element))
+                child_layout.dirty = True
+            layout.children.append(child_layout)
+        node.layout_node = layout
+        return [layout]
+
+    def _build_layout_list(self, node: VNode) -> List[LayoutNode]:
+        """Build fresh (uncached) ``LayoutNode`` for ``node`` and its subtree."""
+        element = node.element
+        if not node.is_native:
+            out: List[LayoutNode] = []
+            for child in node.children:
+                out.extend(self._build_layout_list(child))
+            return out
+        if element.type in DETACHED_TYPES:
+            return []
+        layout = self._new_layout_node(node)
+        for child in node.children:
+            for child_layout in self._build_layout_list(child):
+                if element.type == "ScrollView":
+                    child_layout = self._wrap_scroll_axis(child_layout, self._scroll_axis(element))
+                    child_layout.dirty = True
+                layout.children.append(child_layout)
+        return [layout]
+
+    def _new_layout_node(self, node: VNode) -> LayoutNode:
+        element = node.element
+        layout = LayoutNode(style=extract_layout_style(element.props), user_data=node)
+        layout.dirty = True
+        if element.type == "ScrollView":
+            # Mark the scroll axis so the engine clamps the container's
+            # main-axis size to its parent's available space; otherwise
+            # the container grows to fit its content and nothing scrolls.
+            layout._pn_scroll_axis = self._scroll_axis(element)
+        if not node.children:
+            measure = self._make_measure_callback(node)
+            if measure is not None:
+                layout.measure = measure
+        return layout
+
+    @staticmethod
+    def _scroll_axis(element: Element) -> str:
+        return "x" if element.props.get("scroll_axis", "vertical") == "horizontal" else "y"
+
+    @staticmethod
+    def _direct_child_layouts(layout: LayoutNode, element: Element) -> List[LayoutNode]:
+        """Return the cached child layout nodes, unwrapping ScrollView wrappers."""
+        if element.type == "ScrollView":
+            out: List[LayoutNode] = []
+            for wrapper in layout.children:
+                out.extend(wrapper.children)
+            return out
+        return list(layout.children)
+
+    def _clear_layout_dirty(self, node: VNode) -> None:
+        node.layout_dirty = False
+        layout = node.layout_node
+        if layout is not None:
+            layout.dirty = False
+            for layout_child in layout.children:
+                layout_child.dirty = False
+        for child in node.children:
+            self._clear_layout_dirty(child)
+
+    @staticmethod
+    def _wrap_scroll_axis(child: LayoutNode, axis: str) -> LayoutNode:
+        """Wrap ``child`` so the layout engine treats one axis as unbounded."""
+        wrapper = LayoutNode(style={"flex_direction": "column" if axis == "y" else "row"}, user_data=None)
+        wrapper.children.append(child)
+        return wrapper
+
+    def _make_measure_callback(self, node: VNode) -> Optional[Callable[[float, float], Tuple[float, float]]]:
+        """Return a measure callback for ``node`` if it has an intrinsic size."""
+        if node.tag is None or node.element.type in {
+            "View",
+            "Row",
+            "Column",
+            "ScrollView",
+            "Modal",
+            "Portal",
+            "ScreenStack",
+        }:
+            return None
+        backend = self.backend
+        tag = node.tag
+
+        def measure(max_w: float, max_h: float) -> Tuple[float, float]:
+            cache = node.measure_cache
+            if cache is not None and cache[0] == max_w and cache[1] == max_h:
+                return (cache[2], cache[3])
+            try:
+                w, h = backend.measure_intrinsic(tag, max_w, max_h)
+                result = (float(w), float(h))
+                node.measure_cache = (max_w, max_h, result[0], result[1])
+                return result
+            except Exception:
+                return (0.0, 0.0)
+
+        return measure
+
+    def _collect_frames(self, layout_node: LayoutNode, parent_x: float, parent_y: float) -> None:
+        """Walk a positioned layout tree and emit ``SetFrameOp`` for changed frames.
+
+        Coordinates accumulate through transparent wrapper nodes (the
+        ScrollView axis wrapper) so the native view receives its
+        position relative to its true native parent.
+        """
+        node: Optional[VNode] = layout_node.user_data
+        if node is not None and node.tag is not None:
+            frame: Frame = (
+                layout_node.x + parent_x,
+                layout_node.y + parent_y,
+                layout_node.width,
+                layout_node.height,
+            )
+            if node.last_frame != frame:
+                node.last_frame = frame
+                self._ops.append(SetFrameOp(node.tag, *frame))
+                ref = node.element.props.get("ref")
+                if ref is not None and hasattr(ref, "current"):
+                    try:
+                        ref._pn_frame = frame
+                    except Exception:
+                        pass
+                if "on_layout" in node.element.props:
+                    self._pending_layout_events.append((node.tag, frame))
+            child_x = child_y = 0.0
+        else:
+            child_x = layout_node.x + parent_x
+            child_y = layout_node.y + parent_y
+        for child in layout_node.children:
+            self._collect_frames(child, child_x, child_y)
+
+    def _dispatch_layout_events(self) -> None:
+        """Fire queued ``on_layout`` callbacks after frames were applied."""
+        if not self._pending_layout_events:
+            return
+        from ..events import dispatch_event
+
+        pending, self._pending_layout_events = self._pending_layout_events, []
+        for tag, frame in pending:
+            try:
+                dispatch_event(tag, "on_layout", {"x": frame[0], "y": frame[1], "width": frame[2], "height": frame[3]})
+            except Exception as exc:
+                diagnostics.report_error(exc, phase="event")

pythonnative/reconciler/vnode.py

@@ -0,0 +1,266 @@
+"""Mounted-tree nodes and the pure helpers the reconciler shares.
+
+[`VNode`][pythonnative.reconciler.VNode] pairs an
+[`Element`][pythonnative.Element] with the identity of the native view
+it produced (its **tag**) plus the bookkeeping the reconciler needs
+across passes (layout cache, boundary state, hook state).
+
+Everything in this module is side-effect free with respect to the
+native layer.
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from .. import diagnostics
+from ..component import Component
+from ..element import ERROR_BOUNDARY, FRAGMENT, SUSPENSE, Element, type_label
+from ..hooks import Context, HookState
+from ..layout import LayoutNode
+
+__all__ = [
+    "DETACHED_TYPES",
+    "VNode",
+    "next_tag",
+    "normalize_children",
+    "shallow_equal_props",
+]
+
+# Native element types whose subtree is laid out against the viewport
+# in a detached pass instead of participating in the main layout flow.
+# Their handlers host the children in a separately presented native
+# container (a modal, an overlay, a pushed screen).
+DETACHED_TYPES = frozenset({"Modal", "Portal"})
+
+# Tags are globally unique so multiple reconcilers (screens, list rows)
+# can share one registry without collisions.
+_tag_counter = itertools.count(1)
+
+
+def next_tag() -> int:
+    """Allocate a fresh, process-unique view tag."""
+    return next(_tag_counter)
+
+
+def shallow_equal_props(old: dict, new: dict) -> bool:
+    """Return whether two prop dicts are equal under shallow comparison.
+
+    Used by [`memo`][pythonnative.memo] to skip re-rendering when none
+    of a component's props changed identity. Callables only count as
+    equal if they're the *same object*; fresh closures always invalidate
+    the memo (matching React's behavior; pair with
+    [`use_callback`][pythonnative.use_callback] when stability matters).
+    """
+    if old is new:
+        return True
+    if old.keys() != new.keys():
+        return False
+    for key, ov in old.items():
+        nv = new[key]
+        if ov is nv:
+            continue
+        if callable(ov) or callable(nv):
+            return False
+        try:
+            if ov != nv:
+                return False
+        except Exception:
+            return False
+    return True
+
+
+def normalize_children(children: Any, owner: str = "") -> List[Element]:
+    """Normalize arbitrary render output into a flat list of Elements.
+
+    Accepts a single element, ``None``, ``True``/``False`` (both
+    skipped, enabling inline conditionals like ``cond and Text(...)``),
+    lists/tuples/generators (flattened recursively), and unkeyed
+    Fragments (expanded inline so they never touch the native tree).
+    Keyed Fragments are preserved so they can participate in keyed
+    reconciliation as a unit.
+
+    Non-Element values other than the above are dropped with a
+    dev-mode warning.
+    """
+    out: List[Element] = []
+
+    def add(item: Any) -> None:
+        if item is None or item is True or item is False:
+            return
+        if isinstance(item, Element):
+            if item.type is FRAGMENT and item.key is None:
+                for sub in item.children:
+                    add(sub)
+                return
+            out.append(item)
+            return
+        if isinstance(item, (str, bytes)):
+            diagnostics.warn_once(
+                f"Ignoring bare string child {item!r}"
+                + (f" under {owner}" if owner else "")
+                + ". Wrap text in pn.Text(...).",
+                key=f"strchild:{owner}",
+            )
+            return
+        try:
+            iterator = iter(item)
+        except TypeError:
+            diagnostics.warn_once(
+                f"Ignoring non-Element child {item!r} ({type(item).__name__})"
+                + (f" under {owner}" if owner else "")
+                + ". Children must be Elements, iterables of Elements, or None/False for conditionals.",
+                key=f"badchild:{owner}:{type(item).__name__}",
+            )
+            return
+        for sub in iterator:
+            add(sub)
+
+    add(children)
+
+    if diagnostics.is_dev() and len(out) > 1:
+        seen: Set[Any] = set()
+        for el in out:
+            if el.key is None:
+                continue
+            if el.key in seen:
+                diagnostics.warn_once(
+                    f"Duplicate key {el.key!r} among children"
+                    + (f" of {owner}" if owner else "")
+                    + ". Keys must be unique among siblings; duplicates break "
+                    "keyed reconciliation and can cross-wire component state.",
+                    key=f"dupkey:{owner}:{el.key!r}",
+                )
+            seen.add(el.key)
+    return out
+
+
+class VNode:
+    """A mounted [`Element`][pythonnative.Element] plus its native identity.
+
+    The reconciler walks parallel trees of ``VNode`` and incoming
+    ``Element`` to compute the minimal set of native mutations.
+
+    Attributes:
+        element: The ``Element`` last rendered into this slot.
+        tag: Integer identity of the underlying native view. Native
+            elements own a fresh tag; transparent wrappers (components,
+            providers, boundaries, keyed fragments) delegate the tag of
+            their first native root. ``None`` when the subtree renders
+            no native view.
+        native_view: The platform-native view object, resolved from the
+            backend after commit. ``None`` for wrappers that rendered
+            nothing.
+        children: Ordered list of child ``VNode`` instances.
+        parent: The owning ``VNode``, or ``None`` for the tree root.
+        hook_state: The component's
+            [`HookState`][pythonnative.hooks.HookState] when the node
+            wraps a component, otherwise ``None``.
+        mounted: ``False`` once the node has been destroyed, so stale
+            entries in the reconciler's dirty set are skipped.
+    """
+
+    __slots__ = (
+        "element",
+        "tag",
+        "native_view",
+        "children",
+        "parent",
+        "hook_state",
+        "mounted",
+        "rendered",
+        "clean_props",
+        "measure_cache",
+        "last_frame",
+        "layout_node",
+        "layout_dirty",
+        "error",
+        "suspense_showing_fallback",
+        "suspense_hydration",
+        "suspense_waits",
+    )
+
+    def __init__(self, element: Element, children: Optional[List["VNode"]] = None, tag: Optional[int] = None) -> None:
+        self.element = element
+        self.tag = tag
+        self.native_view: Any = None
+        self.children: List[VNode] = children if children is not None else []
+        self.parent: Optional[VNode] = None
+        self.hook_state: Optional[HookState] = None
+        self.mounted: bool = True
+        # The normalized element list a component body last produced.
+        self.rendered: Optional[List[Element]] = None
+        # Native-safe props (events and reconciler-owned keys stripped)
+        # from the last commit; the baseline for prop diffing.
+        self.clean_props: Dict[str, Any] = {}
+        # Cache for the leaf intrinsic-size measure callback:
+        # ``(max_w, max_h, width, height)``. Invalidated whenever the
+        # node's props change, so unchanged leaves skip native
+        # ``measure_intrinsic`` calls entirely.
+        self.measure_cache: Optional[Tuple[float, float, float, float]] = None
+        # Last frame sent to the native side; unchanged frames are
+        # skipped (frame diffing).
+        self.last_frame: Optional[Tuple[float, float, float, float]] = None
+        # Cached LayoutNode reused across passes while the subtree is
+        # clean (see the layout mixin).
+        self.layout_node: Optional[LayoutNode] = None
+        # True when this node's layout-relevant props or child list
+        # changed since the last layout pass.
+        self.layout_dirty: bool = True
+        # For error-boundary nodes: the caught exception while the
+        # fallback is showing, else ``None``.
+        self.error: Optional[BaseException] = None
+        # For Suspense nodes: whether the fallback is showing, the hook
+        # states of suspended descendants preserved for the next retry
+        # (keyed by ``(component identity, element key)``), and the ids
+        # of waitables already wired to trigger a retry.
+        self.suspense_showing_fallback: bool = False
+        self.suspense_hydration: Optional[Dict[Tuple[int, Any], List[HookState]]] = None
+        self.suspense_waits: Optional[Set[int]] = None
+
+    # ------------------------------------------------------------------
+    # Classification helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def is_native(self) -> bool:
+        """Whether this node owns a native view."""
+        return isinstance(self.element.type, str)
+
+    @property
+    def is_component(self) -> bool:
+        """Whether this node renders a user component (a ``@component`` function)."""
+        return isinstance(self.element.type, Component)
+
+    @property
+    def is_provider(self) -> bool:
+        """Whether this node is a context provider."""
+        return isinstance(self.element.type, Context)
+
+    @property
+    def is_error_boundary(self) -> bool:
+        """Whether this node is an ``ErrorBoundary``."""
+        return self.element.type is ERROR_BOUNDARY
+
+    @property
+    def is_suspense(self) -> bool:
+        """Whether this node is a ``Suspense`` boundary."""
+        return self.element.type is SUSPENSE
+
+    @property
+    def label(self) -> str:
+        """Human-readable name of the element type (for diagnostics and tree dumps)."""
+        return type_label(self.element.type)
+
+    def depth(self) -> int:
+        """Return the number of ancestors above this node (the root has depth 0)."""
+        depth = 0
+        node = self.parent
+        while node is not None:
+            depth += 1
+            node = node.parent
+        return depth
+
+    def __repr__(self) -> str:
+        return f"VNode({self.label!r}, tag={self.tag}, children={len(self.children)})"