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

pythonnative/components.py

@@ -1,16 +1,12 @@
-"""Built-in element factories and the typed prop schemas they share.
+"""Built-in element factories.
 
-Each ``@dataclass(frozen=True)`` class in this module (``TextProps``,
-``ButtonProps``, etc.) is the canonical schema for one built-in
-component. Each factory function (``Text``, ``Button``, …) is a thin
-ergonomic wrapper that builds an [`Element`][pythonnative.Element]
-through the shared :func:`_make_element` helper, so style resolution,
-``ref`` attachment, ``None``-default dropping, and forced overrides
-(e.g. ``Column``'s fixed ``flex_direction``) live in exactly one place.
-
-The same Props dataclasses are used by the `pythonnative.sdk` surface
-for third-party components, so the built-in API and the extension API
-speak the same shape.
+Each factory function (``Text``, ``Button``, …) is a fully-typed thin
+wrapper that builds an [`Element`][pythonnative.Element] through the
+shared :func:`_make_element` helper, so style resolution, ``ref``
+attachment, ``None``-default dropping, and forced overrides (e.g.
+``Column``'s fixed ``flex_direction``) live in exactly one place. The
+factory signatures themselves are the canonical prop schemas: editors
+and type checkers validate calls directly against them.
 
 Example:
     ```python
@@ -18,20 +14,27 @@ Example:
 
     pn.Column(
         pn.Text("Hello", style=pn.style(font_size=18)),
-        pn.Button("Tap", on_click=lambda: print("tapped")),
+        pn.Button("Tap", on_press=lambda: print("tapped")),
         style=pn.style(spacing=12, padding=16),
     )
     ```
 """
 
 import bisect
-from dataclasses import dataclass, field
-from typing import Any, Callable, Dict, List, Literal, Optional, Tuple
+from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Union
 
 from .element import Element
-from .hooks import component, use_effect, use_ref, use_state
-from .sdk import Props
+from .hooks import (
+    Ref,
+    component,
+    use_imperative_handle,
+    use_keyboard_height,
+    use_ref,
+    use_safe_area_insets,
+    use_state,
+)
 from .style import (
+    AccessibilityState,
     AutoCapitalize,
     Color,
     KeyboardType,
@@ -39,6 +42,7 @@ from .style import (
     ScaleType,
     StyleProp,
     resolve_style,
+    validate_style_keys,
 )
 
 # ======================================================================
@@ -50,7 +54,7 @@ def _make_element(
     name: str,
     *children: Element,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
     _defaults: Optional[Dict[str, Any]] = None,
     _forced: Optional[Dict[str, Any]] = None,
@@ -78,8 +82,9 @@ def _make_element(
         name: Element type name (e.g. ``"Text"``).
         *children: Child elements.
         style: Style dict, list of dicts, or ``None``.
-        ref: Optional ``use_ref()`` dict; the reconciler populates
-            ``ref["current"]`` with the underlying native view.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``; the
+            reconciler populates ``ref.current`` with the underlying
+            native view.
         key: Stable identity for keyed reconciliation.
         _defaults: Internal: fill-only-if-missing prop defaults.
         _forced: Internal: prop overrides applied last.
@@ -89,6 +94,8 @@ def _make_element(
         A fresh [`Element`][pythonnative.Element].
     """
     out: Dict[str, Any] = dict(resolve_style(style))
+    if out:
+        validate_style_keys(out, owner=name)
     if _defaults:
         for k, v in _defaults.items():
             out.setdefault(k, v)
@@ -103,325 +110,75 @@ def _make_element(
 
 
 # ======================================================================
-# Props dataclasses
+# Leaf factories
 # ======================================================================
-#
-# These are the canonical schemas for every built-in component. They
-# subclass the SDK's ``Props`` base, so the same shape works for both
-# the built-in factory functions and the third-party
-# [`element_factory`][pythonnative.element_factory] API.
-
-
-@dataclass(frozen=True)
-class TextProps(Props):
-    """Props for [`Text`][pythonnative.Text]."""
-
-    text: str = ""
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class ButtonProps(Props):
-    """Props for [`Button`][pythonnative.Button]."""
-
-    title: str = ""
-    on_click: Optional[Callable[[], None]] = None
-    enabled: bool = True
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class TextInputProps(Props):
-    """Props for [`TextInput`][pythonnative.TextInput]."""
-
-    value: str = ""
-    placeholder: Optional[str] = None
-    on_change: Optional[Callable[[str], None]] = None
-    on_submit: Optional[Callable[[str], None]] = None
-    secure: bool = False
-    multiline: bool = False
-    keyboard_type: Optional[KeyboardType] = None
-    auto_capitalize: Optional[AutoCapitalize] = None
-    auto_correct: Optional[bool] = None
-    auto_focus: bool = False
-    return_key_type: Optional[ReturnKeyType] = None
-    max_length: Optional[int] = None
-    placeholder_color: Optional[Color] = None
-    editable: bool = True
-    clear_button: bool = False
-    on_focus: Optional[Callable[[], None]] = None
-    on_blur: Optional[Callable[[], None]] = None
-    selection_color: Optional[Color] = None
-    text_content_type: Optional[str] = None
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class ImageProps(Props):
-    """Props for [`Image`][pythonnative.Image]."""
-
-    source: Optional[str] = None
-    scale_type: Optional[ScaleType] = None
-    tint_color: Optional[Color] = None
-    accessibility_label: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class SwitchProps(Props):
-    """Props for [`Switch`][pythonnative.Switch]."""
-
-    value: bool = False
-    on_change: Optional[Callable[[bool], None]] = None
-    accessibility_label: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class ProgressBarProps(Props):
-    """Props for [`ProgressBar`][pythonnative.ProgressBar]."""
-
-    value: float = 0.0
-    color: Optional[Color] = None
-    track_color: Optional[Color] = None
-    indeterminate: bool = False
-
-
-@dataclass(frozen=True)
-class ActivityIndicatorProps(Props):
-    """Props for [`ActivityIndicator`][pythonnative.ActivityIndicator]."""
-
-    animating: bool = True
-    color: Optional[Color] = None
-    size: Literal["small", "large"] = "small"
-
-
-@dataclass(frozen=True)
-class WebViewProps(Props):
-    """Props for [`WebView`][pythonnative.WebView]."""
-
-    url: Optional[str] = None
-    html: Optional[str] = None
-    on_load: Optional[Callable[[str], None]] = None
-    on_message: Optional[Callable[[str], None]] = None
-    on_navigation_state_change: Optional[Callable[[str], None]] = None
-    inject_javascript: Optional[str] = None
-    scroll_enabled: bool = True
-
-
-@dataclass(frozen=True)
-class SpacerProps(Props):
-    """Props for [`Spacer`][pythonnative.Spacer]."""
-
-    size: Optional[float] = None
-    flex: Optional[float] = None
-
-
-@dataclass(frozen=True)
-class SliderProps(Props):
-    """Props for [`Slider`][pythonnative.Slider]."""
-
-    value: float = 0.0
-    min_value: float = 0.0
-    max_value: float = 1.0
-    on_change: Optional[Callable[[float], None]] = None
-    accessibility_label: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class ViewProps(Props):
-    """Props for [`View`][pythonnative.View], [`Column`][pythonnative.Column], and [`Row`][pythonnative.Row]."""
-
-    gestures: Optional[List[Any]] = None
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
 
-@dataclass(frozen=True)
-class ScrollViewProps(Props):
-    """Props for [`ScrollView`][pythonnative.ScrollView].
-
-    ``on_scroll`` receives a single payload dict with ``"x"`` and
-    ``"y"`` content offsets in points.
-    """
-
-    refresh_control: Optional[Dict[str, Any]] = None
-    scroll_axis: Optional[Literal["vertical", "horizontal"]] = None
-    on_scroll: Optional[Callable[[Dict[str, float]], None]] = None
-    shows_scroll_indicator: bool = True
-    paging_enabled: bool = False
-    bounces: bool = True
-    content_container_style: StyleProp = None
-    keyboard_dismiss_mode: Optional[Literal["none", "on_drag", "interactive"]] = None
-
-
-@dataclass(frozen=True)
-class SafeAreaViewProps(Props):
-    """Props for [`SafeAreaView`][pythonnative.SafeAreaView]."""
-
-
-@dataclass(frozen=True)
-class ModalProps(Props):
-    """Props for [`Modal`][pythonnative.Modal]."""
-
-    visible: bool = False
-    on_dismiss: Optional[Callable[[], None]] = None
-    on_show: Optional[Callable[[], None]] = None
-    title: Optional[str] = None
-    animation_type: Literal["slide", "fade", "none"] = "slide"
-    transparent: bool = False
-    presentation_style: Literal["page_sheet", "form_sheet", "full_screen", "overlay"] = "page_sheet"
-    dismiss_on_backdrop: bool = True
-
-
-@dataclass(frozen=True)
-class PressableProps(Props):
-    """Props for [`Pressable`][pythonnative.Pressable]."""
-
-    on_press: Optional[Callable[[], None]] = None
-    on_long_press: Optional[Callable[[], None]] = None
-    on_press_in: Optional[Callable[[], None]] = None
-    on_press_out: Optional[Callable[[], None]] = None
-    pressed_opacity: float = 0.6
-    gestures: Optional[List[Any]] = None
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class StatusBarProps(Props):
-    """Props for [`StatusBar`][pythonnative.StatusBar]."""
-
-    bar_style: Optional[Literal["light", "dark", "default"]] = None
-    background_color: Optional[Color] = None
-    hidden: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class KeyboardAvoidingViewProps(Props):
-    """Props for [`KeyboardAvoidingView`][pythonnative.KeyboardAvoidingView]."""
-
-    behavior: Literal["padding", "position"] = "padding"
 
+# Style keys that can vary per span inside a rich-text run. Layout
+# keys are excluded: spans are inline fragments of one paragraph and
+# have no boxes of their own.
+_SPAN_STYLE_KEYS = (
+    "color",
+    "background_color",
+    "font_size",
+    "font_family",
+    "font_weight",
+    "bold",
+    "italic",
+    "text_decoration",
+    "letter_spacing",
+)
 
-@dataclass(frozen=True)
-class PickerProps(Props):
-    """Props for [`Picker`][pythonnative.Picker].
 
-    ``items`` is an ordered list of ``{"value": Any, "label": str}``
-    entries. ``value`` is matched against ``items[i]["value"]`` to
-    determine the currently selected row.
-    """
+def _flatten_text_spans(
+    parts: Tuple[Any, ...],
+    inherited: Dict[str, Any],
+) -> List[Dict[str, Any]]:
+    """Flatten nested ``Text`` parts into a flat list of styled spans.
 
-    value: Any = None
-    items: List[Dict[str, Any]] = field(default_factory=list)
-    on_change: Optional[Callable[[Any], None]] = None
-    placeholder: str = "Select…"
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class TouchableOpacityProps(Props):
-    """Props for [`TouchableOpacity`][pythonnative.TouchableOpacity]."""
-
-    on_press: Optional[Callable[[], None]] = None
-    on_long_press: Optional[Callable[[], None]] = None
-    active_opacity: float = 0.2
-    disabled: bool = False
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessibility_role: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class ImageBackgroundProps(Props):
-    """Props for [`ImageBackground`][pythonnative.ImageBackground]."""
-
-    source: Optional[str] = None
-    scale_type: Optional[ScaleType] = None
-    accessibility_label: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class CheckboxProps(Props):
-    """Props for [`Checkbox`][pythonnative.Checkbox]."""
-
-    value: bool = False
-    on_change: Optional[Callable[[bool], None]] = None
-    label: Optional[str] = None
-    disabled: bool = False
-    color: Optional[Color] = None
-    accessibility_label: Optional[str] = None
-    accessibility_hint: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class SegmentedControlProps(Props):
-    """Props for [`SegmentedControl`][pythonnative.SegmentedControl]."""
-
-    segments: List[str] = field(default_factory=list)
-    selected_index: int = 0
-    on_change: Optional[Callable[[int], None]] = None
-    enabled: bool = True
-    tint_color: Optional[Color] = None
-    accessibility_label: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-@dataclass(frozen=True)
-class DatePickerProps(Props):
-    """Props for [`DatePicker`][pythonnative.DatePicker].
-
-    ``value`` and the value passed to ``on_change`` are ISO-8601
-    strings (``"2026-05-31"`` for ``mode="date"``, ``"14:30"`` for
-    ``mode="time"``, ``"2026-05-31T14:30"`` for ``mode="datetime"``),
-    so the schema stays JSON-serializable and platform-agnostic.
+    Strings become spans carrying only the inherited style overrides;
+    nested ``Text`` elements contribute their own span-style keys
+    (merged over what they inherit) and recurse into their parts.
     """
-
-    value: Optional[str] = None
-    mode: Literal["date", "time", "datetime"] = "date"
-    on_change: Optional[Callable[[str], None]] = None
-    minimum: Optional[str] = None
-    maximum: Optional[str] = None
-    enabled: bool = True
-    accessibility_label: Optional[str] = None
-    accessible: Optional[bool] = None
-
-
-# ======================================================================
-# Leaf factories
-# ======================================================================
+    spans: List[Dict[str, Any]] = []
+    for part in parts:
+        if part is None:
+            continue
+        if isinstance(part, Element):
+            props = part.props or {}
+            child_style = dict(inherited)
+            for k in _SPAN_STYLE_KEYS:
+                if props.get(k) is not None:
+                    child_style[k] = props[k]
+            nested = props.get("spans")
+            if nested:
+                for span in nested:
+                    merged = dict(child_style)
+                    for k in _SPAN_STYLE_KEYS:
+                        if span.get(k) is not None:
+                            merged[k] = span[k]
+                    spans.append({"text": span.get("text", ""), **merged})
+            else:
+                spans.append({"text": str(props.get("text", "")), **child_style})
+        else:
+            spans.append({"text": str(part), **inherited})
+    return spans
 
 
 def Text(
-    text: str = "",
-    *,
+    *parts: Any,
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Display a string of text.
+    """Display a string of text, optionally with styled nested spans.
 
     Style properties: ``font_size``, ``color``, ``bold``,
     ``font_weight``, ``font_family``, ``italic``, ``text_align``,
@@ -431,43 +188,87 @@ def Text(
     ``border_color``, ``shadow_*``, ``opacity``, ``transform``, plus
     the common layout props.
 
+    **Rich text**: pass multiple parts, mixing plain strings and
+    nested ``Text`` elements, to render one paragraph with per-span
+    styling (a single ``TextView`` / ``UILabel`` natively, so line
+    wrapping flows across spans):
+
+    ```python
+    pn.Text(
+        "Hello, ",
+        pn.Text("world", style=pn.style(bold=True, color="#0A84FF")),
+        "!",
+        style=pn.style(font_size=18),
+    )
+    ```
+
+    Nested spans inherit the outer element's text styling and may
+    override ``color``, ``background_color``, ``font_size``,
+    ``font_family``, ``font_weight``, ``bold``, ``italic``,
+    ``text_decoration``, and ``letter_spacing``.
+
     Args:
-        text: Text content to display.
+        *parts: Text content: a single string, or any mix of strings
+            and nested ``Text`` elements for rich text.
         style: Style dict (or list of dicts).
         accessibility_label: Spoken description for screen readers.
         accessibility_hint: Spoken extra detail (iOS only).
         accessibility_role: Semantic role for assistive tech.
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
         An [`Element`][pythonnative.Element] of type ``"Text"``.
     """
+    rich = any(isinstance(p, Element) for p in parts) or len(parts) > 1
+    if rich:
+        spans = _flatten_text_spans(parts, {})
+        text = "".join(s["text"] for s in spans)
+    else:
+        spans = None
+        text = str(parts[0]) if parts else ""
     return _make_element(
         "Text",
         style=style,
         ref=ref,
         key=key,
         text=text,
+        spans=spans,
         accessibility_label=accessibility_label,
         accessibility_hint=accessibility_hint,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
     )
 
 
 def Button(
     title: str = "",
     *,
-    on_click: Optional[Callable[[], None]] = None,
+    on_press: Optional[Callable[[], None]] = None,
     enabled: bool = True,
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Display a tappable button.
@@ -480,7 +281,7 @@ def Button(
 
     Args:
         title: Button label.
-        on_click: Callback invoked when the user taps the button.
+        on_press: Callback invoked when the user taps the button.
         enabled: When ``False``, the button is disabled and cannot be
             tapped.
         style: Style dict (or list of dicts).
@@ -488,7 +289,17 @@ def Button(
         accessibility_hint: Spoken extra detail (iOS only).
         accessibility_role: Override the default ``"button"`` role.
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -500,12 +311,15 @@ def Button(
         ref=ref,
         key=key,
         title=title,
-        on_click=on_click,
+        on_press=on_press,
         enabled=enabled,
         accessibility_label=accessibility_label,
         accessibility_hint=accessibility_hint,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "button"},
     )
 
@@ -535,7 +349,10 @@ def TextInput(
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Display a text-entry field (single-line by default, or ``multiline``).
@@ -575,7 +392,17 @@ def TextInput(
         accessibility_label: Spoken description for screen readers.
         accessibility_hint: Spoken extra detail (iOS only).
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -608,6 +435,9 @@ def TextInput(
         accessibility_label=accessibility_label,
         accessibility_hint=accessibility_hint,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
     )
 
 
@@ -616,11 +446,17 @@ def Image(
     *,
     scale_type: Optional[ScaleType] = None,
     tint_color: Optional[Color] = None,
+    placeholder_color: Optional[Color] = None,
+    on_load: Optional[Callable[[], None]] = None,
+    on_error: Optional[Callable[[str], None]] = None,
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Display an image from a resource path or URL.
@@ -628,10 +464,11 @@ def Image(
     Style properties: ``background_color``, ``border_*``, ``opacity``,
     ``transform``, plus the common layout props.
 
-    Network images (``http://`` / ``https://``) are loaded
-    asynchronously off the main thread on both iOS (via
-    ``NSURLSession``) and Android (via a worker thread plus
-    ``BitmapFactory``).
+    Network images (``http://`` / ``https://``) go through the shared
+    image pipeline (`pythonnative.images`): downloads happen on a
+    background thread, bytes are cached in memory and on disk keyed by
+    URL, concurrent requests for the same URL share one download, and
+    large bitmaps are downsampled to the view size when decoded.
 
     Args:
         source: Image resource name or URL.
@@ -639,11 +476,27 @@ def Image(
             ``"center"``.
         tint_color: Color overlay applied to template images
             (monochrome icons).
+        placeholder_color: Background color shown while a remote image
+            is loading (and left in place if it fails).
+        on_load: Callback invoked once the image has been decoded and
+            displayed.
+        on_error: Callback invoked with an error message when a remote
+            image fails to download or decode.
         style: Style dict (or list of dicts).
         accessibility_label: Spoken description for screen readers.
         accessibility_role: Override the default ``"image"`` role.
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -657,9 +510,15 @@ def Image(
         source=source or None,
         scale_type=scale_type,
         tint_color=tint_color,
+        placeholder_color=placeholder_color,
+        on_load=on_load,
+        on_error=on_error,
         accessibility_label=accessibility_label,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "image"},
     )
 
@@ -900,7 +759,10 @@ def View(
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Universal flex container (like React Native's ``View``).
@@ -939,7 +801,17 @@ def View(
         accessibility_hint: Spoken extra detail (iOS only).
         accessibility_role: Semantic role for assistive tech.
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -956,6 +828,9 @@ def View(
         accessibility_hint=accessibility_hint,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"flex_direction": "column"},
     )
 
@@ -963,7 +838,7 @@ def View(
 def Column(
     *children: Element,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Arrange children vertically.
@@ -975,7 +850,7 @@ def Column(
     Args:
         *children: Child elements stacked top to bottom.
         style: Style dict (or list of dicts).
-        ref: Optional ``use_ref()`` dict for native-view access.
+        ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -994,7 +869,7 @@ def Column(
 def Row(
     *children: Element,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Arrange children horizontally.
@@ -1006,7 +881,7 @@ def Row(
     Args:
         *children: Child elements arranged left to right.
         style: Style dict (or list of dicts).
-        ref: Optional ``use_ref()`` dict for native-view access.
+        ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1033,7 +908,7 @@ def ScrollView(
     content_container_style: StyleProp = None,
     keyboard_dismiss_mode: Optional[Literal["none", "on_drag", "interactive"]] = None,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Wrap children in a scrollable container.
@@ -1064,7 +939,7 @@ def ScrollView(
             ``"interactive"``. Controls whether scrolling dismisses
             the keyboard.
         style: Style dict (or list of dicts).
-        ref: Optional ``use_ref()`` dict.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1087,25 +962,76 @@ def ScrollView(
     )
 
 
+_SAFE_AREA_EDGES: Tuple[str, ...] = ("top", "left", "bottom", "right")
+
+
+def _numeric_edge_padding(style: Dict[str, Any], edge: str) -> float:
+    """Return the numeric padding already declared for ``edge`` in ``style``.
+
+    Only numeric values participate; percentage strings and dict
+    shorthands are left alone (the inset simply overrides them for
+    that edge). Resolution order matches the layout engine:
+    ``padding_{edge}`` beats the axis shorthand, which beats
+    ``padding``.
+    """
+    axis_key = "padding_vertical" if edge in ("top", "bottom") else "padding_horizontal"
+    for key in (f"padding_{edge}", axis_key, "padding"):
+        value = style.get(key)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return float(value)
+    return 0.0
+
+
+@component
+def _SafeAreaContainer(**p: Any) -> Element:
+    """Hook-driven body of `SafeAreaView`.
+
+    Reads the live insets via
+    [`use_safe_area_insets`][pythonnative.use_safe_area_insets] (so the
+    subtree re-renders when the platform publishes new values, e.g. on
+    rotation) and adds each selected edge's inset on top of any padding
+    the user declared for that edge.
+    """
+    insets = use_safe_area_insets()
+    style: Dict[str, Any] = dict(p.get("style") or {})
+    edges = p.get("edges") or _SAFE_AREA_EDGES
+    for edge in _SAFE_AREA_EDGES:
+        if edge not in edges:
+            continue
+        inset = float(insets.get(edge, 0.0) or 0.0)
+        if inset > 0:
+            style[f"padding_{edge}"] = _numeric_edge_padding(style, edge) + inset
+    children = p.get("children") or []
+    return Element("SafeAreaView", style, list(children))
+
+
 def SafeAreaView(
     *children: Element,
+    edges: Optional[Tuple[Literal["top", "left", "bottom", "right"], ...]] = None,
     style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
     """Container that respects safe-area insets (notch, status bar, home indicator).
 
+    Applies the platform-reported insets as extra padding on the
+    selected edges and re-renders automatically when the insets change
+    (rotation, split view). User padding on an inset edge is added to
+    the inset, matching ``react-native-safe-area-context``.
+
     Args:
         *children: Child elements that should avoid system UI overlays.
+        edges: Which edges to pad; defaults to all four.
         style: Style dict (or list of dicts).
         key: Stable identity for keyed reconciliation.
 
     Returns:
-        An [`Element`][pythonnative.Element] of type ``"SafeAreaView"``.
+        An [`Element`][pythonnative.Element] that renders a
+        ``"SafeAreaView"`` container.
     """
-    return _make_element(
-        "SafeAreaView",
-        *children,
-        style=style,
+    return _SafeAreaContainer(
+        children=list(children),
+        edges=tuple(edges) if edges else None,
+        style=resolve_style(style),
         key=key,
     )
 
@@ -1175,6 +1101,41 @@ def Modal(
     )
 
 
+@component
+def _StatefulPressable(**p: Any) -> Element:
+    """Hook-driven Pressable used when ``style`` is a callable.
+
+    Tracks the pressed state with ``use_state`` and re-invokes the
+    user's style function with ``{"pressed": bool}`` on every press
+    transition, mirroring React Native's function-style ``style`` prop.
+    """
+    pressed, set_pressed = use_state(False)
+    style_fn = p["style_fn"]
+    user_press_in = p.get("on_press_in")
+    user_press_out = p.get("on_press_out")
+
+    def _press_in() -> None:
+        set_pressed(True)
+        if user_press_in is not None:
+            user_press_in()
+
+    def _press_out() -> None:
+        set_pressed(False)
+        if user_press_out is not None:
+            user_press_out()
+
+    forwarded = {k: v for k, v in p.items() if k not in ("children", "style_fn", "on_press_in", "on_press_out")}
+    return _make_element(
+        "Pressable",
+        *(p.get("children") or []),
+        style=resolve_style(style_fn({"pressed": pressed})),
+        on_press_in=_press_in,
+        on_press_out=_press_out,
+        _defaults={"accessibility_role": "button"},
+        **forwarded,
+    )
+
+
 def Pressable(
     *children: Element,
     on_press: Optional[Callable[[], None]] = None,
@@ -1183,12 +1144,15 @@ def Pressable(
     on_press_out: Optional[Callable[[], None]] = None,
     pressed_opacity: float = 0.6,
     gestures: Optional[List[Any]] = None,
-    style: StyleProp = None,
+    style: Union[StyleProp, Callable[[Dict[str, bool]], StyleProp]] = None,
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Wrap children with tap / long-press / gesture handlers.
@@ -1210,17 +1174,60 @@ def Pressable(
         gestures: Optional list of gesture descriptors from
             `pythonnative.gestures` recognized natively on this view
             (pan / swipe / pinch / rotation / multi-tap).
-        style: Style dict applied to the wrapper.
+        style: Style dict applied to the wrapper, or a callable
+            receiving the interaction state (``{"pressed": bool}``)
+            and returning a style, re-evaluated on every press
+            transition:
+
+            ```python
+            pn.Pressable(
+                pn.Text("Tap"),
+                style=lambda s: pn.style(
+                    background_color="#0051A8" if s["pressed"] else "#007AFF",
+                ),
+            )
+            ```
         accessibility_label: Spoken description for screen readers.
         accessibility_hint: Spoken extra detail (iOS only).
         accessibility_role: Override the default ``"button"`` role.
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
-        An [`Element`][pythonnative.Element] of type ``"Pressable"``.
+        An [`Element`][pythonnative.Element] of type ``"Pressable"``
+        (wrapped in a stateful composite when ``style`` is callable).
     """
+    if callable(style):
+        return _StatefulPressable(
+            children=list(children),
+            style_fn=style,
+            ref=ref,
+            key=key,
+            on_press=on_press,
+            on_long_press=on_long_press,
+            on_press_in=on_press_in,
+            on_press_out=on_press_out,
+            pressed_opacity=pressed_opacity,
+            gestures=gestures,
+            accessibility_label=accessibility_label,
+            accessibility_hint=accessibility_hint,
+            accessibility_role=accessibility_role,
+            accessible=accessible,
+            accessibility_state=accessibility_state,
+            accessibility_live_region=accessibility_live_region,
+            test_id=test_id,
+        )
     return _make_element(
         "Pressable",
         *children,
@@ -1237,6 +1244,9 @@ def Pressable(
         accessibility_hint=accessibility_hint,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "button"},
     )
 
@@ -1257,6 +1267,9 @@ def TouchableOpacity(
     accessibility_hint: Optional[str] = None,
     accessibility_role: Optional[str] = None,
     accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Wrap children so they fade to ``active_opacity`` while pressed.
@@ -1278,6 +1291,16 @@ def TouchableOpacity(
         accessibility_hint: Spoken extra detail (iOS only).
         accessibility_role: Override the default ``"button"`` role.
         accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1300,6 +1323,9 @@ def TouchableOpacity(
         accessibility_hint=accessibility_hint,
         accessibility_role=accessibility_role,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         key=key,
     )
 
@@ -1311,6 +1337,9 @@ def ImageBackground(
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Render ``children`` layered on top of a background image.
@@ -1329,6 +1358,16 @@ def ImageBackground(
         style: Style dict for the container (size, padding, alignment).
         accessibility_label: Spoken description of the background image.
         accessible: Override whether the image is exposed to AT.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1342,6 +1381,9 @@ def ImageBackground(
         style=fill,
         accessibility_label=accessibility_label,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
     )
     content = View(*children, style={"flex": 1})
     return View(
@@ -1363,6 +1405,9 @@ def Checkbox(
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     key: Optional[str] = None,
 ) -> Element:
     """A boolean checkbox with an optional inline label.
@@ -1381,6 +1426,16 @@ def Checkbox(
         accessibility_label: Spoken description for screen readers.
         accessibility_hint: Spoken extra detail (iOS only).
         accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1398,6 +1453,9 @@ def Checkbox(
         accessibility_label=accessibility_label,
         accessibility_hint=accessibility_hint,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "checkbox"},
     )
 
@@ -1412,6 +1470,9 @@ def SegmentedControl(
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     key: Optional[str] = None,
 ) -> Element:
     """A horizontal multi-choice control (one selected segment at a time).
@@ -1428,6 +1489,16 @@ def SegmentedControl(
         style: Style dict (or list of dicts).
         accessibility_label: Spoken description for screen readers.
         accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1445,6 +1516,9 @@ def SegmentedControl(
         tint_color=tint_color,
         accessibility_label=accessibility_label,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
     )
 
 
@@ -1459,6 +1533,9 @@ def DatePicker(
     style: StyleProp = None,
     accessibility_label: Optional[str] = None,
     accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     key: Optional[str] = None,
 ) -> Element:
     """A native date / time picker.
@@ -1466,7 +1543,10 @@ def DatePicker(
     Backed by ``UIDatePicker`` on iOS and a trigger button that opens
     the platform ``DatePickerDialog`` / ``TimePickerDialog`` on
     Android. ``value`` and the value reported to ``on_change`` are
-    ISO-8601 strings (see [`DatePickerProps`][pythonnative.DatePickerProps]).
+    ISO-8601 strings (``"2026-05-31"`` for ``mode="date"``, ``"14:30"``
+    for ``mode="time"``, ``"2026-05-31T14:30"`` for
+    ``mode="datetime"``), so values stay JSON-serializable and
+    platform-agnostic.
 
     Args:
         value: Currently selected value as an ISO-8601 string.
@@ -1478,6 +1558,16 @@ def DatePicker(
         style: Style dict (or list of dicts).
         accessibility_label: Spoken description for screen readers.
         accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1495,6 +1585,9 @@ def DatePicker(
         enabled=False if enabled is False else None,
         accessibility_label=accessibility_label,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "button"},
     )
 
@@ -1507,14 +1600,12 @@ def DatePicker(
 def Fragment(*children: Optional[Element], key: Optional[str] = None) -> Element:
     """Group children without adding a wrapping native view.
 
-    Like React's ``<></>``: returns multiple elements from a component
-    without introducing an extra container. The reconciler flattens
-    Fragment elements at the children-list level, so each child appears
-    as a direct sibling of the Fragment's parent in the native tree.
-
-    Useful inside [`Provider`][pythonnative.Provider] /
-    [`memo`][pythonnative.memo] / conditional logic when grouping
-    siblings inside another component's child list:
+    Like React's ``<></>``: groups elements without introducing an
+    extra container. Each child mounts as a direct sibling of the
+    Fragment's position in the parent's child list. Components may
+    also simply return a plain ``list`` of elements; ``Fragment``
+    exists for when the group needs a ``key`` (e.g. rendering a list
+    of pairs) or when a single expression reads better.
 
     ```python
     pn.Column(
@@ -1528,24 +1619,54 @@ def Fragment(*children: Optional[Element], key: Optional[str] = None) -> Element
     ```
 
     Args:
-        *children: Child elements to expose at the parent level. ``None``
-            children are dropped, which makes conditional rendering with
-            ``cond and pn.Text(...)`` ergonomic.
-        key: Optional key for the Fragment itself (rarely useful since
-            Fragment doesn't appear in the native tree).
+        *children: Child elements to expose at the parent level.
+            ``None`` and ``False`` children are dropped, which makes
+            conditional rendering with ``cond and pn.Text(...)``
+            ergonomic.
+        key: Stable identity for keyed reconciliation. A keyed
+            Fragment moves all of its children as one unit and
+            preserves their state across reorders.
 
     Returns:
         An [`Element`][pythonnative.Element] of type ``"__Fragment__"``.
+    """
+    kept = [c for c in children if c is not None and c is not False]
+    return Element("__Fragment__", {}, kept, key=key)
 
-    Note:
-        Today, returning a Fragment from a ``@pn.component`` function
-        only mounts its first child as the component's root. To return
-        multiple top-level elements from a function component, use a
-        container such as [`Column`][pythonnative.Column] or
-        [`Row`][pythonnative.Row] instead.
+
+def Portal(*children: Element, key: Optional[str] = None) -> Element:
+    """Render ``children`` into a full-screen overlay above everything else.
+
+    Like React DOM's ``createPortal``: the children stay part of this
+    component's tree for state, context, and events, but their native
+    views mount in a transparent overlay attached to the window (above
+    the screen's content) instead of inside the surrounding parent.
+    Use it for toasts, dropdowns, tooltips, and lightweight custom
+    overlays that must escape ``overflow: "hidden"`` ancestors. For a
+    system-styled dialog with its own presentation and dismissal
+    gestures, use [`Modal`][pythonnative.Modal] instead.
+
+    The overlay itself does not intercept touches; only the children
+    themselves are hit-testable. Children are laid out against the
+    full viewport, so position them with absolute insets:
+
+    ```python
+    pn.Portal(
+        pn.View(
+            pn.Text("Saved!"),
+            style=pn.style(position="absolute", bottom=40, left=40, right=40),
+        ),
+    )
+    ```
+
+    Args:
+        *children: Overlay content.
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"Portal"``.
     """
-    filtered = [c for c in children if c is not None]
-    return Element("__Fragment__", {}, filtered, key=key)
+    return Element("Portal", {}, list(children), key=key)
 
 
 # ======================================================================
@@ -1556,23 +1677,33 @@ def Fragment(*children: Optional[Element], key: Optional[str] = None) -> Element
 def ErrorBoundary(
     *children: Element,
     fallback: Optional[Any] = None,
+    on_error: Optional[Callable[[BaseException], None]] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Catch render errors in the wrapped subtree and display ``fallback`` instead.
 
-    ``fallback`` may be an [`Element`][pythonnative.Element] or a
-    callable that receives the exception and returns an ``Element``.
-    Useful for isolating risky subtrees so a single failure doesn't
-    crash the page.
+    When any descendant raises during render (initial mount, a parent
+    re-render, or a local state-driven update), the failed subtree is
+    torn down and ``fallback`` is mounted in its place. Without a
+    boundary the error propagates to the screen host (which shows the
+    dev error overlay in dev mode).
 
-    When multiple children are passed they're grouped under a
-    [`Fragment`][pythonnative.Fragment] so the boundary still wraps a
-    single logical subtree.
+    ``fallback`` may be:
+
+    - An [`Element`][pythonnative.Element], shown as-is.
+    - ``fallback(error) -> Element``.
+    - ``fallback(error, reset) -> Element``, where ``reset`` is a
+      zero-arg callable that clears the error and remounts the
+      original children (fresh state), for retry buttons.
 
     Args:
         *children: Subtree to wrap.
-        fallback: Element rendered when the subtree raises during
-            render, or a callable ``fallback(err) -> Element``.
+        fallback: Fallback content (see above). Required for the
+            boundary to actually catch; without it errors propagate
+            to the next boundary up.
+        on_error: Callback invoked with the exception when the
+            boundary catches, before the fallback mounts. Use it for
+            error reporting.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -1585,32 +1716,43 @@ def ErrorBoundary(
 
         pn.ErrorBoundary(
             MyRiskyComponent(),
-            fallback=lambda err: pn.Text(f"Error: {err}"),
+            fallback=lambda err, reset: pn.Column(
+                pn.Text(f"Error: {err}"),
+                pn.Button("Retry", on_press=reset),
+            ),
+            on_error=lambda err: log.exception(err),
         )
         ```
     """
     props: Dict[str, Any] = {}
     if fallback is not None:
         props["__fallback__"] = fallback
-    if len(children) <= 1:
-        kids = list(children)
-    else:
-        kids = [Fragment(*children)]
-    return Element("__ErrorBoundary__", props, kids, key=key)
+    if on_error is not None:
+        props["__on_error__"] = on_error
+    return Element("__ErrorBoundary__", props, list(children), key=key)
 
 
 # ======================================================================
-# Lists (Python-windowed virtualization over ScrollView)
+# Lists (native virtualization with a Python-windowed fallback)
 # ======================================================================
 #
-# FlatList and SectionList are pure Python components, not native
-# elements. They render a windowed slice of rows into a ScrollView
-# (leading spacer, visible rows, trailing spacer) and shift the window
-# from scroll events (the same architecture as React Native's
-# VirtualizedList). Because every windowed row lives in the *main*
-# layout tree, rows may be any height: estimates only steer the spacer
-# sizes, and each row's measured extent is fed back from the layout
-# pass through its ref to correct the estimates over time.
+# FlatList and SectionList pick between two engines:
+#
+# 1. **Native virtualization** (`_NativeList` -> the ``VirtualList``
+#    element): on Android and iOS, when every row extent is known up
+#    front and no windowed-only feature is requested, the list is
+#    backed by a real ``RecyclerView`` / ``UITableView``. The platform
+#    owns row recycling; each visible row hosts a nested-reconciler
+#    subtree (see ``pythonnative.virtual_rows``).
+# 2. **Python windowing** (`_VirtualizedList`): a windowed slice of
+#    rows rendered into a ScrollView (leading spacer, visible rows,
+#    trailing spacer), the window shifting from scroll events (the
+#    same architecture as React Native's VirtualizedList). Because
+#    every windowed row lives in the *main* layout tree, rows may be
+#    any height: estimates steer the spacer sizes and measured extents
+#    correct them over time. This is the desktop path and the fallback
+#    for variable-height rows, grids, horizontal lists, ornaments, and
+#    pull-to-refresh.
 
 _DEFAULT_ROW_EXTENT = 44.0
 
@@ -1637,7 +1779,7 @@ class _RowSpec:
 
 def _dispatch_scroll_command(scroll_ref: Any, name: str, args: Dict[str, Any]) -> Any:
     """Send an imperative command to the ScrollView under ``scroll_ref``."""
-    tag = scroll_ref.get("_pn_tag") if isinstance(scroll_ref, dict) else None
+    tag = getattr(scroll_ref, "_pn_tag", None)
     if tag is None:
         return None
     from .native_views import get_registry
@@ -1648,6 +1790,55 @@ def _dispatch_scroll_command(scroll_ref: Any, name: str, args: Dict[str, Any]) -
         return None
 
 
+class ListController:
+    """Imperative scroll handle published on a list's ``ref``.
+
+    [`FlatList`][pythonnative.FlatList] and
+    [`SectionList`][pythonnative.SectionList] install a
+    ``ListController`` on ``ref.current`` (via
+    [`use_imperative_handle`][pythonnative.use_imperative_handle])
+    after mount and clear it back to ``None`` on unmount.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Chat(messages):
+            list_ref = pn.use_ref()
+            pn.use_layout_effect(
+                lambda: list_ref.current and list_ref.current.scroll_to_end(animated=False),
+                [len(messages)],
+            )
+            return pn.FlatList(data=messages, render_item=Bubble, ref=list_ref)
+        ```
+    """
+
+    __slots__ = ("_scroll_to_offset", "_scroll_to_index", "_scroll_to_end")
+
+    def __init__(
+        self,
+        scroll_to_offset: Callable[[float, bool], None],
+        scroll_to_index: Callable[[int, bool], None],
+        scroll_to_end: Callable[[bool], None],
+    ) -> None:
+        self._scroll_to_offset = scroll_to_offset
+        self._scroll_to_index = scroll_to_index
+        self._scroll_to_end = scroll_to_end
+
+    def scroll_to_offset(self, offset: float, animated: bool = True) -> None:
+        """Scroll to an absolute content offset in points."""
+        self._scroll_to_offset(offset, animated)
+
+    def scroll_to_index(self, index: int, animated: bool = True) -> None:
+        """Scroll so the row at ``index`` sits at the top of the viewport."""
+        self._scroll_to_index(index, animated)
+
+    def scroll_to_end(self, animated: bool = True) -> None:
+        """Scroll to the end of the content."""
+        self._scroll_to_end(animated)
+
+
 @component
 def _VirtualizedList(**p: Any) -> Element:
     """Shared windowing engine behind FlatList and SectionList."""
@@ -1659,18 +1850,18 @@ def _VirtualizedList(**p: Any) -> Element:
     initial_extent: float = float(p.get("initial_window_extent") or 800.0)
 
     window, set_window = use_state((0, -1))
-    measured = use_ref({})  # row key -> measured extent (points)
-    row_refs = use_ref({})  # row key -> ref dict for live rows
+    measured: Ref[Dict[str, float]] = use_ref({})  # row key -> measured extent (points)
+    row_refs: Ref[Dict[str, Ref]] = use_ref({})  # row key -> Ref for live rows
     end_latch = use_ref({"fired_for": -1})
-    viewable_ref = use_ref({"keys": ()})
+    viewable_ref: Ref[Dict[str, Tuple[str, ...]]] = use_ref({"keys": ()})
     scroll_pos = use_ref({"offset": 0.0})
-    sv_ref = use_ref(None)
+    sv_ref: Ref = use_ref(None)
 
     # ------------------------------------------------------------------
     # Extent model: measured > per-row hint > estimate. ``starts`` are
     # prefix sums; ``starts[n]`` is the total content extent.
     # ------------------------------------------------------------------
-    measured_map: Dict[str, float] = measured["current"]
+    measured_map: Dict[str, float] = measured.current
     starts: List[float] = [0.0] * (n + 1)
     acc = 0.0
     for i, spec in enumerate(rows):
@@ -1683,7 +1874,7 @@ def _VirtualizedList(**p: Any) -> Element:
     total_extent = acc
 
     def _viewport_extent() -> float:
-        frame = sv_ref.get("_pn_frame") if isinstance(sv_ref, dict) else None
+        frame = sv_ref._pn_frame
         if frame:
             extent = frame[2] if horizontal else frame[3]
             if extent and extent > 0:
@@ -1702,7 +1893,7 @@ def _VirtualizedList(**p: Any) -> Element:
 
     first, last = window
     if last < 0 or first >= n:
-        first, last = _window_for(scroll_pos["current"]["offset"], _viewport_extent())
+        first, last = _window_for(scroll_pos.current["offset"], _viewport_extent())
     last = min(last, n - 1)
     first = max(0, min(first, max(0, n - 1)))
 
@@ -1718,8 +1909,8 @@ def _VirtualizedList(**p: Any) -> Element:
     user_on_scroll = p.get("on_scroll")
 
     def _sweep_measured() -> None:
-        for row_key, ref in row_refs["current"].items():
-            frame = ref.get("_pn_frame") if isinstance(ref, dict) else None
+        for row_key, row_ref in row_refs.current.items():
+            frame = getattr(row_ref, "_pn_frame", None)
             if frame:
                 extent = frame[2] if horizontal else frame[3]
                 if extent and extent > 0:
@@ -1730,7 +1921,7 @@ def _VirtualizedList(**p: Any) -> Element:
             offset = float(payload.get("x" if horizontal else "y", 0.0) or 0.0)
         else:
             offset = float(payload or 0.0)
-        scroll_pos["current"]["offset"] = offset
+        scroll_pos.current["offset"] = offset
         _sweep_measured()
         viewport = _viewport_extent()
 
@@ -1741,18 +1932,18 @@ def _VirtualizedList(**p: Any) -> Element:
         if on_end_reached is not None and total_extent > 0:
             remaining = total_extent - (offset + viewport)
             if remaining <= end_threshold * viewport:
-                if end_latch["current"]["fired_for"] != n:
-                    end_latch["current"]["fired_for"] = n
+                if end_latch.current["fired_for"] != n:
+                    end_latch.current["fired_for"] = n
                     on_end_reached()
             elif remaining > end_threshold * viewport + viewport:
-                end_latch["current"]["fired_for"] = -1
+                end_latch.current["fired_for"] = -1
 
         if on_viewable is not None and n > 0:
             v_first = max(0, bisect.bisect_right(starts, offset, 0, n) - 1)
             v_last = min(n - 1, bisect.bisect_left(starts, offset + viewport, 0, n))
             keys = tuple(rows[i].key for i in range(v_first, v_last + 1))
-            if keys != viewable_ref["current"]["keys"]:
-                viewable_ref["current"]["keys"] = keys
+            if keys != viewable_ref.current["keys"]:
+                viewable_ref.current["keys"] = keys
                 on_viewable(
                     [
                         {"index": rows[i].index, "key": rows[i].key, "item": rows[i].item}
@@ -1764,33 +1955,26 @@ def _VirtualizedList(**p: Any) -> Element:
             user_on_scroll(payload)
 
     # ------------------------------------------------------------------
-    # Imperative controller (scroll_to_index / offset / end) exposed on
-    # the user's ref dict. Re-attached every render so the closures see
-    # fresh extents; the effect itself must run unconditionally to keep
-    # hook order stable.
+    # Imperative controller (scroll_to_index / offset / end) published
+    # on the user's ref. Rebuilt every render (deps=None) so the
+    # closures see fresh extents.
     # ------------------------------------------------------------------
-    controller = p.get("controller_ref")
-
-    def _attach_controller() -> None:
-        if not isinstance(controller, dict):
-            return
-
-        def scroll_to_offset(offset: float, animated: bool = True) -> None:
-            axis = "x" if horizontal else "y"
-            _dispatch_scroll_command(sv_ref, "scroll_to_offset", {axis: float(offset), "animated": animated})
-
-        def scroll_to_index(index: int, animated: bool = True) -> None:
-            idx = max(0, min(int(index), n - 1)) if n else 0
-            scroll_to_offset(starts[idx], animated)
+    def _scroll_to_offset(offset: float, animated: bool = True) -> None:
+        axis = "x" if horizontal else "y"
+        _dispatch_scroll_command(sv_ref, "scroll_to_offset", {axis: float(offset), "animated": animated})
 
-        def scroll_to_end(animated: bool = True) -> None:
-            scroll_to_offset(max(0.0, total_extent - _viewport_extent()), animated)
+    def _scroll_to_index(index: int, animated: bool = True) -> None:
+        idx = max(0, min(int(index), n - 1)) if n else 0
+        _scroll_to_offset(starts[idx], animated)
 
-        controller["scroll_to_offset"] = scroll_to_offset
-        controller["scroll_to_index"] = scroll_to_index
-        controller["scroll_to_end"] = scroll_to_end
+    def _scroll_to_end(animated: bool = True) -> None:
+        _scroll_to_offset(max(0.0, total_extent - _viewport_extent()), animated)
 
-    use_effect(_attach_controller, None)
+    use_imperative_handle(
+        p.get("controller_ref"),
+        lambda: ListController(_scroll_to_offset, _scroll_to_index, _scroll_to_end),
+        None,
+    )
 
     # ------------------------------------------------------------------
     # Children: header, leading spacer, windowed rows, trailing spacer,
@@ -1809,17 +1993,17 @@ def _VirtualizedList(**p: Any) -> Element:
         if empty is not None:
             children.append(View(empty, key="__pn_empty__"))
     else:
-        live_refs: Dict[str, Any] = {}
+        live_refs: Dict[str, Ref] = {}
         lead = starts[first]
         if lead > 0:
             lead_style: Dict[str, Any] = {spacer_key: lead}
             children.append(View(style=lead_style, key="__pn_lead__"))
         for i in range(first, last + 1):
             spec = rows[i]
-            row_ref = row_refs["current"].get(spec.key) or {"current": None}
+            row_ref = row_refs.current.get(spec.key) or Ref()
             live_refs[spec.key] = row_ref
             children.append(View(spec.make(), ref=row_ref, key=spec.key))
-        row_refs["current"] = live_refs
+        row_refs.current = live_refs
         trail = total_extent - starts[last + 1]
         if trail > 0:
             trail_style: Dict[str, Any] = {spacer_key: trail}
@@ -1841,6 +2025,126 @@ def _VirtualizedList(**p: Any) -> Element:
     )
 
 
+def _native_lists_supported() -> bool:
+    """Whether the natively virtualized list path is available.
+
+    Android (RecyclerView) and iOS (UITableView) have native handlers;
+    the desktop preview and off-device tests use the Python-windowed
+    engine. Patchable in tests to exercise the native routing.
+    """
+    from .utils import IS_ANDROID, IS_IOS
+
+    return IS_ANDROID or IS_IOS
+
+
+@component
+def _NativeList(**p: Any) -> Element:
+    """Platform-virtualized list: emits a ``VirtualList`` native element.
+
+    The native side (RecyclerView / UITableView) owns row windowing and
+    recycling; each visible row hosts a nested-reconciler subtree (see
+    ``pythonnative.virtual_rows``). This composite adapts the FlatList /
+    SectionList surface onto that element: it forwards ``render_row``,
+    derives ``on_end_reached`` and ``on_viewable_items_changed`` from
+    native scroll reports, and wires the imperative scroll controller.
+
+    Requires every row's extent to be known up front (the native
+    virtualizers need exact heights before rows are rendered); callers
+    fall back to the Python-windowed engine otherwise.
+    """
+    rows: List[_RowSpec] = p.get("rows") or []
+    n = len(rows)
+    heights: List[float] = [float(spec.extent or 0.0) for spec in rows]
+    uniform = len(set(heights)) <= 1
+
+    internal_ref: Ref = use_ref(None)
+    end_latch = use_ref({"fired_for": -1})
+    viewable_ref: Ref[Dict[str, Tuple[str, ...]]] = use_ref({"keys": ()})
+
+    starts: List[float] = [0.0] * (n + 1)
+    acc = 0.0
+    for i, extent in enumerate(heights):
+        starts[i] = acc
+        acc += max(0.0, extent)
+    starts[n] = acc
+    total_extent = acc
+
+    def _render_row(index: int) -> Element:
+        if 0 <= index < n:
+            return rows[index].make()
+        return View()
+
+    on_end_reached = p.get("on_end_reached")
+    end_threshold = float(p.get("on_end_reached_threshold") or 0.5)
+    on_viewable = p.get("on_viewable_items_changed")
+    user_on_scroll = p.get("on_scroll")
+
+    def _handle_scroll(payload: Any) -> None:
+        offset = float(payload.get("y", 0.0) or 0.0) if isinstance(payload, dict) else float(payload or 0.0)
+        viewport = float(payload.get("extent", 0.0) or 0.0) if isinstance(payload, dict) else 0.0
+        if viewport <= 0:
+            viewport = 800.0
+
+        if on_end_reached is not None and total_extent > 0:
+            remaining = total_extent - (offset + viewport)
+            if remaining <= end_threshold * viewport:
+                if end_latch.current["fired_for"] != n:
+                    end_latch.current["fired_for"] = n
+                    on_end_reached()
+            elif remaining > end_threshold * viewport + viewport:
+                end_latch.current["fired_for"] = -1
+
+        if on_viewable is not None and n > 0:
+            v_first = max(0, bisect.bisect_right(starts, offset, 0, n) - 1)
+            v_last = min(n - 1, bisect.bisect_left(starts, offset + viewport, 0, n))
+            keys = tuple(rows[i].key for i in range(v_first, v_last + 1))
+            if keys != viewable_ref.current["keys"]:
+                viewable_ref.current["keys"] = keys
+                on_viewable(
+                    [
+                        {"index": rows[i].index, "key": rows[i].key, "item": rows[i].item}
+                        for i in range(v_first, v_last + 1)
+                    ]
+                )
+
+        if user_on_scroll is not None:
+            user_on_scroll({"x": 0.0, "y": offset})
+
+    def _scroll_to_offset(offset: float, animated: bool = True) -> None:
+        _dispatch_scroll_command(internal_ref, "scroll_to_offset", {"y": float(offset), "animated": animated})
+
+    def _scroll_to_index(index: int, animated: bool = True) -> None:
+        _dispatch_scroll_command(internal_ref, "scroll_to_index", {"index": int(index), "animated": animated})
+
+    def _scroll_to_end(animated: bool = True) -> None:
+        _dispatch_scroll_command(internal_ref, "scroll_to_end", {"animated": animated})
+
+    use_imperative_handle(
+        p.get("controller_ref"),
+        lambda: ListController(_scroll_to_offset, _scroll_to_index, _scroll_to_end),
+        None,
+    )
+
+    props: Dict[str, Any] = dict(p.get("list_style") or {})
+    props["count"] = n
+    if uniform:
+        props["row_height"] = heights[0] if heights else _DEFAULT_ROW_EXTENT
+    else:
+        props["row_heights"] = heights
+    props["render_row"] = _render_row
+    props["ref"] = internal_ref
+    wants_scroll = on_end_reached is not None or on_viewable is not None or user_on_scroll is not None
+    if wants_scroll:
+        props["on_scroll"] = _handle_scroll
+    if p.get("shows_scroll_indicator") is False:
+        props["shows_scroll_indicator"] = False
+    return Element("VirtualList", props, [])
+
+
+def _all_extents_known(rows: List[_RowSpec]) -> bool:
+    return all(spec.extent is not None for spec in rows)
+
+
 def FlatList(
     *,
     data: Optional[List[Any]] = None,
@@ -1863,7 +2167,7 @@ def FlatList(
     shows_scroll_indicator: bool = True,
     content_container_style: StyleProp = None,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Virtualized scrollable list that renders items from ``data`` lazily.
@@ -1876,10 +2180,12 @@ def FlatList(
     unknown rows start at ``estimated_item_height`` and are corrected
     with their measured extent once they've been on screen.
 
-    The ``ref`` dict (from [`use_ref`][pythonnative.use_ref]) is
-    populated with an imperative controller:
-    ``ref["scroll_to_index"](i)``, ``ref["scroll_to_offset"](pts)``,
-    and ``ref["scroll_to_end"]()``.
+    Pass a [`Ref`][pythonnative.Ref] (from
+    [`use_ref`][pythonnative.use_ref]) to receive a
+    [`ListController`][pythonnative.ListController] on ``ref.current``:
+    ``ref.current.scroll_to_index(i)``,
+    ``ref.current.scroll_to_offset(pts)``, and
+    ``ref.current.scroll_to_end()``.
 
     Args:
         data: List of arbitrary item values.
@@ -1914,8 +2220,9 @@ def FlatList(
         content_container_style: Style applied to the inner content
             wrapper.
         style: Style for the outer scroll container.
-        ref: Optional ``use_ref()`` dict; receives the scroll
-            controller functions.
+        ref: Optional [`Ref`][pythonnative.Ref]; receives a
+            [`ListController`][pythonnative.ListController] on
+            ``ref.current`` after mount.
         key: Stable identity for keyed reconciliation of the list.
 
     Returns:
@@ -1994,6 +2301,32 @@ def FlatList(
 
     estimated = estimated_item_height if estimated_item_height is not None else (item_height or _DEFAULT_ROW_EXTENT)
 
+    # Route to the platform virtualizer (RecyclerView / UITableView)
+    # when it can represent this list exactly: vertical, single-column,
+    # every row extent known up front, and no features that only the
+    # Python-windowed engine implements (ornaments, pull-to-refresh).
+    if (
+        _native_lists_supported()
+        and not horizontal
+        and num_columns == 1
+        and list_header is None
+        and list_footer is None
+        and list_empty is None
+        and refresh_control is None
+        and _all_extents_known(rows)
+    ):
+        return _NativeList(
+            rows=rows,
+            on_end_reached=on_end_reached,
+            on_end_reached_threshold=on_end_reached_threshold,
+            on_viewable_items_changed=on_viewable_items_changed,
+            on_scroll=on_scroll,
+            shows_scroll_indicator=shows_scroll_indicator,
+            list_style=resolve_style(style) or None,
+            controller_ref=ref,
+            key=key,
+        )
+
     return _VirtualizedList(
         rows=rows,
         horizontal=horizontal,
@@ -2033,7 +2366,7 @@ def SectionList(
     on_end_reached_threshold: float = 0.5,
     on_scroll: Optional[Callable[[Dict[str, float]], None]] = None,
     style: StyleProp = None,
-    ref: Optional[Dict[str, Any]] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """Virtualized list with section headers interleaved between row groups.
@@ -2067,8 +2400,9 @@ def SectionList(
             multiples, at which ``on_end_reached`` fires.
         on_scroll: Called with the raw scroll payload.
         style: Style for the outer scroll container.
-        ref: Optional ``use_ref()`` dict; receives the scroll
-            controller functions.
+        ref: Optional [`Ref`][pythonnative.Ref]; receives a
+            [`ListController`][pythonnative.ListController] on
+            ``ref.current`` after mount.
         key: Stable identity for keyed reconciliation of the list.
 
     Returns:
@@ -2132,6 +2466,26 @@ def SectionList(
 
     estimated = estimated_item_height if estimated_item_height is not None else (item_height or _DEFAULT_ROW_EXTENT)
 
+    # Same native routing as FlatList: headers and items become one
+    # flattened row sequence with per-row heights.
+    if (
+        _native_lists_supported()
+        and list_header is None
+        and list_footer is None
+        and list_empty is None
+        and refresh_control is None
+        and _all_extents_known(rows)
+    ):
+        return _NativeList(
+            rows=rows,
+            on_end_reached=on_end_reached,
+            on_end_reached_threshold=on_end_reached_threshold,
+            on_scroll=on_scroll,
+            list_style=resolve_style(style) or None,
+            controller_ref=ref,
+            key=key,
+        )
+
     return _VirtualizedList(
         rows=rows,
         horizontal=False,
@@ -2194,9 +2548,40 @@ def StatusBar(
     return Element("StatusBar", props, [], key=key)
 
 
+@component
+def _KeyboardAvoidingContainer(**p: Any) -> Element:
+    """Hook-driven body of `KeyboardAvoidingView`.
+
+    Subscribes to the platform-reported keyboard height via
+    [`use_keyboard_height`][pythonnative.use_keyboard_height] and
+    applies the shift according to ``behavior``:
+
+    - ``"padding"``: adds the shift as bottom padding, resizing the
+      content area (the default, and the right choice for forms
+      inside a full-height container).
+    - ``"position"``: translates the whole container upward without
+      resizing it (useful for pinned footers/toolbars).
+    """
+    height = use_keyboard_height()
+    behavior = p.get("behavior") or "padding"
+    offset = float(p.get("keyboard_vertical_offset") or 0.0)
+    shift = max(0.0, height - offset) if height > 0 else 0.0
+    style: Dict[str, Any] = dict(p.get("style") or {})
+    if shift > 0:
+        if behavior == "position":
+            transform = list(style.get("transform") or [])
+            transform.append({"translate_y": -shift})
+            style["transform"] = transform
+        else:
+            style["padding_bottom"] = _numeric_edge_padding(style, "bottom") + shift
+    children = p.get("children") or []
+    return Element("KeyboardAvoidingView", style, list(children))
+
+
 def KeyboardAvoidingView(
     *children: Element,
     behavior: Literal["padding", "position"] = "padding",
+    keyboard_vertical_offset: float = 0.0,
     style: StyleProp = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -2204,26 +2589,32 @@ def KeyboardAvoidingView(
 
     Subscribes to the platform-reported keyboard height (via
     [`use_keyboard_height`][pythonnative.use_keyboard_height]
-    internally) and applies it as bottom padding so the focused text
-    input stays visible.
+    internally) and shifts its content so the focused text input stays
+    visible. On iOS the height comes from
+    ``UIKeyboardWillShowNotification``; on Android from the window's
+    IME insets.
 
     Args:
         *children: Children rendered inside the avoiding container.
-        behavior: ``"padding"`` (adds bottom padding) or ``"position"``
-            (translates the container upward).
+        behavior: ``"padding"`` (adds bottom padding, resizing the
+            content) or ``"position"`` (translates the container
+            upward without resizing).
+        keyboard_vertical_offset: Distance in layout units already
+            covered by other UI (e.g. a nav bar); subtracted from the
+            keyboard height before applying the shift.
         style: Style dict (or list of dicts).
         key: Stable identity for keyed reconciliation.
 
     Returns:
-        An [`Element`][pythonnative.Element] of type
-        ``"KeyboardAvoidingView"``.
+        An [`Element`][pythonnative.Element] that renders a
+        ``"KeyboardAvoidingView"`` container.
     """
-    return _make_element(
-        "KeyboardAvoidingView",
-        *children,
-        style=style,
-        key=key,
+    return _KeyboardAvoidingContainer(
+        children=list(children),
         behavior=behavior,
+        keyboard_vertical_offset=keyboard_vertical_offset,
+        style=resolve_style(style),
+        key=key,
     )
 
 
@@ -2291,7 +2682,10 @@ def Picker(
     accessibility_label: Optional[str] = None,
     accessibility_hint: Optional[str] = None,
     accessible: Optional[bool] = None,
-    ref: Optional[Dict[str, Any]] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
+    ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
     """A real native dropdown / select widget.
@@ -2314,7 +2708,17 @@ def Picker(
         accessibility_label: Spoken description for screen readers.
         accessibility_hint: Spoken extra detail (iOS only).
         accessible: Override whether the element is exposed to AT.
-        ref: Optional ``use_ref()`` dict.
+        accessibility_state: Current widget state for assistive tech,
+            e.g. ``{"disabled": True, "selected": False}``. Recognized
+            keys: ``disabled``, ``selected``, ``checked``, ``busy``,
+            ``expanded``.
+        accessibility_live_region: How AT announces dynamic changes to
+            this view: ``"none"``, ``"polite"``, or ``"assertive"``
+            (Android only).
+        test_id: Stable identifier for UI tests; exposed as
+            ``resource-id`` on Android and ``accessibilityIdentifier``
+            on iOS.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
         key: Stable identity for keyed reconciliation.
 
     Returns:
@@ -2332,5 +2736,8 @@ def Picker(
         accessibility_label=accessibility_label,
         accessibility_hint=accessibility_hint,
         accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _defaults={"accessibility_role": "button"},
     )