pythonnative 0.40.0__cp314-cp314-win_amd64.whl

pythonnative/components/media.py

@@ -0,0 +1,204 @@
+"""Media factories: ``Image``, ``ImageBackground``, and ``WebView``."""
+
+from typing import Any, Callable, Literal, Optional
+
+from ..element import Element
+from ..hooks import Ref
+from ..style import AccessibilityState, Color, ScaleType, StyleProp, resolve_style
+from ._base import _make_element
+from .layout import View
+
+
+def Image(
+    source: str = "",
+    *,
+    scale_type: Optional[ScaleType] = None,
+    tint_color: Optional[Color] = None,
+    placeholder_color: Optional[Color] = None,
+    on_load: Optional[Callable[[], Any]] = None,
+    on_error: Optional[Callable[[str], Any]] = None,
+    style: StyleProp = None,
+    accessibility_label: 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,
+    ref: Optional[Ref] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display an image from a resource path or URL.
+
+    Style properties: ``background_color``, ``border_*``, ``opacity``,
+    ``transform``, plus the common layout props.
+
+    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.
+        scale_type: Fit mode: ``"cover"``, ``"contain"``, ``"stretch"``,
+            ``"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.
+        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 ``"Image"``.
+    """
+    return _make_element(
+        "Image",
+        style=style,
+        ref=ref,
+        key=key,
+        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"},
+    )
+
+
+def ImageBackground(
+    *children: Element,
+    source: str = "",
+    scale_type: Optional[ScaleType] = None,
+    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.
+
+    Composed entirely from existing primitives: an absolutely-filled
+    [`Image`][pythonnative.Image] sits behind a content
+    [`View`][pythonnative.View] holding ``children``. The container's
+    ``style`` controls sizing/padding; the image stretches to fill it
+    via ``position: "absolute"`` and zeroed insets.
+
+    Args:
+        *children: Foreground content drawn over the image.
+        source: Image resource name or URL.
+        scale_type: Background fit mode (``"cover"`` is the most common
+            for backgrounds).
+        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:
+        An [`Element`][pythonnative.Element] of type ``"View"`` wrapping
+        the background image and foreground content.
+    """
+    fill = {"position": "absolute", "top": 0, "left": 0, "right": 0, "bottom": 0}
+    background = Image(
+        source,
+        scale_type=scale_type or "cover",
+        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(
+        background,
+        content,
+        style=[{"overflow": "hidden"}, resolve_style(style)],
+        key=key,
+    )
+
+
+def WebView(
+    *,
+    url: str = "",
+    html: Optional[str] = None,
+    on_load: Optional[Callable[[str], Any]] = None,
+    on_message: Optional[Callable[[str], Any]] = None,
+    on_navigation_state_change: Optional[Callable[[str], Any]] = None,
+    inject_javascript: Optional[str] = None,
+    scroll_enabled: bool = True,
+    style: StyleProp = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Embed web content from a URL or an inline HTML string.
+
+    Args:
+        url: HTTP(S) URL to load. Ignored when ``html`` is given.
+        html: Inline HTML markup to render instead of loading a URL.
+        on_load: Callback invoked with the final URL once a page
+            finishes loading.
+        on_message: Callback invoked with the string payload whenever
+            page JavaScript calls
+            ``window.pythonnative.postMessage(...)``.
+        on_navigation_state_change: Callback invoked with the URL each
+            time the top-level document begins navigating.
+        inject_javascript: JavaScript evaluated after each page load
+            (useful for installing the ``postMessage`` bridge or
+            tweaking the DOM).
+        scroll_enabled: When ``False``, disables scrolling inside the
+            web content.
+        style: Style dict (or list of dicts).
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"WebView"``.
+    """
+    return _make_element(
+        "WebView",
+        style=style,
+        key=key,
+        url=url or None,
+        html=html,
+        on_load=on_load,
+        on_message=on_message,
+        on_navigation_state_change=on_navigation_state_change,
+        inject_javascript=inject_javascript,
+        scroll_enabled=False if scroll_enabled is False else None,
+    )

pythonnative/components/overlays.py

@@ -0,0 +1,107 @@
+"""Overlay factories: ``Modal`` (native presentation) and ``Portal`` (window overlay)."""
+
+from typing import Any, Callable, Literal, Optional
+
+from ..element import Element
+from ..style import StyleProp
+from ._base import _make_element
+
+
+def Modal(
+    *children: Element,
+    visible: bool = False,
+    on_dismiss: Optional[Callable[[], Any]] = None,
+    on_show: Optional[Callable[[], Any]] = 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,
+    style: StyleProp = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Overlay modal dialog backed by a real native presentation.
+
+    The modal is shown when ``visible=True`` and hidden when ``False``.
+    Drive ``visible`` from a hook so the parent component can dismiss
+    the modal in response to user actions. On iOS this presents a
+    ``UIViewController``; on Android it shows an ``android.app.Dialog``.
+
+    Children are mounted as the modal's content view, not into the
+    on-tree placeholder, so they appear above all other native content
+    and don't influence the underlying layout.
+
+    Args:
+        *children: Modal content.
+        visible: Controls whether the modal is presented.
+        on_dismiss: Callback invoked when the user dismisses the modal
+            via system gesture.
+        on_show: Callback invoked once the modal has finished
+            presenting.
+        title: Optional title-bar text.
+        animation_type: ``"slide"`` (default), ``"fade"``, or ``"none"``.
+        transparent: When ``True``, the underlying view is dimmed
+            instead of fully covered.
+        presentation_style: iOS presentation style,
+            ``"page_sheet"`` (default), ``"form_sheet"``,
+            ``"full_screen"``, or ``"overlay"`` (custom dimmed
+            overlay). On Android, ``"overlay"`` keeps the dialog
+            non-fullscreen.
+        dismiss_on_backdrop: When ``True`` (default) and
+            ``transparent`` / ``"overlay"``, tapping the dimmed
+            backdrop dismisses the modal.
+        style: Style dict (or list of dicts).
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"Modal"``.
+    """
+    return _make_element(
+        "Modal",
+        *children,
+        style=style,
+        key=key,
+        visible=visible,
+        animation_type=animation_type,
+        transparent=transparent,
+        presentation_style=presentation_style,
+        dismiss_on_backdrop=False if dismiss_on_backdrop is False else None,
+        on_dismiss=on_dismiss,
+        on_show=on_show,
+        title=title,
+    )
+
+
+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"``.
+    """
+    return Element("Portal", {}, list(children), key=key)

pythonnative/components/pressable.py

@@ -0,0 +1,252 @@
+"""Touch wrappers: ``Pressable`` and its ``TouchableOpacity`` alias."""
+
+from typing import Any, Callable, Dict, List, Literal, Optional, Union
+
+from ..component import component
+from ..element import Element
+from ..hooks import Ref, use_state
+from ..style import AccessibilityState, StyleProp, resolve_style
+from ._base import _make_element
+
+
+@component
+def _StatefulPressable(
+    *children: Element,
+    style_fn: Optional[Callable[[Dict[str, bool]], StyleProp]] = None,
+    on_press_in: Optional[Callable[[], Any]] = None,
+    on_press_out: Optional[Callable[[], Any]] = None,
+    **props: 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.
+    Every other keyword (``on_press``, ``ref``, accessibility props,
+    ...) is forwarded untouched to the native ``Pressable`` element.
+    """
+    pressed, set_pressed = use_state(False)
+
+    def _press_in() -> None:
+        set_pressed(True)
+        if on_press_in is not None:
+            on_press_in()
+
+    def _press_out() -> None:
+        set_pressed(False)
+        if on_press_out is not None:
+            on_press_out()
+
+    style = resolve_style(style_fn({"pressed": pressed})) if style_fn is not None else None
+    return _make_element(
+        "Pressable",
+        *children,
+        style=style,
+        on_press_in=_press_in,
+        on_press_out=_press_out,
+        _defaults={"accessibility_role": "button"},
+        **props,
+    )
+
+
+def Pressable(
+    *children: Element,
+    on_press: Optional[Callable[[], Any]] = None,
+    on_long_press: Optional[Callable[[], Any]] = None,
+    on_press_in: Optional[Callable[[], Any]] = None,
+    on_press_out: Optional[Callable[[], Any]] = None,
+    pressed_opacity: float = 0.6,
+    gestures: Optional[List[Any]] = None,
+    hit_slop: Optional[Union[float, Dict[str, float]]] = None,
+    on_layout: Optional[Callable[[Dict[str, float]], None]] = 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,
+    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.
+
+    Useful for making non-button elements (text, images, custom views)
+    respond to user taps. The wrapper view fades to ``pressed_opacity``
+    on touch-down and back to full opacity on touch-up.
+
+    Pressable gets ``accessibility_role="button"`` by default.
+
+    Args:
+        *children: Elements to make pressable.
+        on_press: Callback invoked on a normal tap.
+        on_long_press: Callback invoked on a sustained press.
+        on_press_in: Callback invoked the moment the press starts.
+        on_press_out: Callback invoked when the press lifts or cancels.
+        pressed_opacity: Opacity (0–1) applied while the user's finger
+            is down. Set to ``1.0`` for no visual feedback.
+        gestures: Optional list of gesture descriptors from
+            `pythonnative.gestures` recognized natively on this view
+            (pan / swipe / pinch / rotation / multi-tap).
+        hit_slop: Extend the touch target beyond the view's bounds
+            without changing layout: a uniform number of points, or a
+            dict with any of ``top`` / ``left`` / ``bottom`` /
+            ``right``. Essential for small touch targets (icons,
+            chips) that should honor the 44-point guideline.
+        on_layout: Callback invoked with
+            ``{"x", "y", "width", "height"}`` after layout and on
+            frame changes.
+        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.
+        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"``
+        (wrapped in a stateful composite when ``style`` is callable).
+    """
+    if callable(style):
+        return _StatefulPressable(
+            *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,
+            hit_slop=hit_slop,
+            on_layout=on_layout,
+            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,
+        style=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,
+        hit_slop=hit_slop,
+        on_layout=on_layout,
+        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"},
+    )
+
+
+def TouchableOpacity(
+    *children: Element,
+    on_press: Optional[Callable[[], Any]] = None,
+    on_long_press: Optional[Callable[[], Any]] = None,
+    active_opacity: float = 0.2,
+    disabled: bool = False,
+    style: StyleProp = None,
+    accessibility_label: Optional[str] = None,
+    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.
+
+    A thin ergonomic alias over [`Pressable`][pythonnative.Pressable]
+    that mirrors React Native's ``TouchableOpacity``: the only visual
+    feedback is an opacity dip on touch-down. When ``disabled`` is set,
+    the press callbacks are dropped so the wrapper is inert.
+
+    Args:
+        *children: Elements to make tappable.
+        on_press: Callback invoked on a normal tap.
+        on_long_press: Callback invoked on a sustained press.
+        active_opacity: Opacity (0–1) applied while the finger is down.
+        disabled: When ``True``, ignores presses and renders at reduced
+            opacity.
+        style: Style dict applied to the wrapper.
+        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.
+        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:
+        An [`Element`][pythonnative.Element] of type ``"Pressable"``.
+    """
+    merged_style: StyleProp
+    if disabled:
+        base = resolve_style(style)
+        base.setdefault("opacity", 0.4)
+        merged_style = base
+    else:
+        merged_style = style
+    return Pressable(
+        *children,
+        on_press=None if disabled else on_press,
+        on_long_press=None if disabled else on_long_press,
+        pressed_opacity=active_opacity,
+        style=merged_style,
+        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,
+        key=key,
+    )