pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/components/structural.py

@@ -0,0 +1,167 @@
+"""Structural factories: ``Fragment``, ``ErrorBoundary``, and ``Suspense``.
+
+These produce elements whose ``type`` is one of the reconciler-owned
+singletons from [`pythonnative.element`][pythonnative.element]
+(``FRAGMENT``, ``ERROR_BOUNDARY``, ``SUSPENSE``) rather than a native
+view name, so they never create a platform view of their own.
+"""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..element import ERROR_BOUNDARY, FRAGMENT, SUSPENSE, Element
+
+
+def Fragment(*children: Optional[Element], key: Optional[str] = None) -> Element:
+    """Group children without adding a wrapping native view.
+
+    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(
+        pn.Text("Top"),
+        pn.Fragment(
+            pn.Text("Middle A"),
+            pn.Text("Middle B"),
+        ),
+        pn.Text("Bottom"),
+    )
+    ```
+
+    Args:
+        *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] whose type is
+        [`FRAGMENT`][pythonnative.element.FRAGMENT].
+    """
+    kept = [c for c in children if c is not None and c is not False]
+    return Element(FRAGMENT, {}, kept, key=key)
+
+
+def ErrorBoundary(
+    *children: Element,
+    fallback: Optional[Any] = None,
+    on_error: Optional[Callable[[BaseException], Any]] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Catch render errors in the wrapped subtree and display ``fallback`` instead.
+
+    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).
+
+    ``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: 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:
+        An [`Element`][pythonnative.Element] whose type is
+        [`ERROR_BOUNDARY`][pythonnative.element.ERROR_BOUNDARY], with
+        ``fallback`` and ``on_error`` in its props (omitted when
+        ``None``).
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        pn.ErrorBoundary(
+            MyRiskyComponent(),
+            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 on_error is not None:
+        props["on_error"] = on_error
+    return Element(ERROR_BOUNDARY, props, list(children), key=key)
+
+
+def Suspense(
+    *children: Element,
+    fallback: Optional[Any] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Show ``fallback`` while descendants wait on async work, then swap in the content.
+
+    A Suspense boundary catches **suspensions** from the subtree it
+    wraps: an ``async def`` component body blocking on a pending
+    await, or a regular component calling
+    [`Resource.read`][pythonnative.suspense.Resource.read] on data that hasn't
+    arrived (see [`use_resource`][pythonnative.use_resource] and
+    [`lazy`][pythonnative.lazy]). While anything is pending the
+    boundary renders ``fallback``; when the awaited work completes it
+    retries the content and swaps it in. Suspended components keep
+    their hook state across retries, so cached resources aren't
+    refetched.
+
+    Two timing behaviors, matching React:
+
+    - **Initial mount**: the fallback shows until the content is ready.
+    - **Updates**: a component that's already on screen and suspends
+      again (its dependencies changed) keeps its previous content
+      visible and re-renders when ready; there's no fallback flash.
+
+    Args:
+        *children: Subtree to wrap (the async content).
+        fallback: Content shown while suspended: an
+            [`Element`][pythonnative.Element] or a zero-arg callable
+            returning one. Without it, suspensions propagate to the
+            next Suspense boundary up.
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] whose type is
+        [`SUSPENSE`][pythonnative.element.SUSPENSE], with ``fallback``
+        in its props.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        async def Profile(user_id: str):
+            user = await api.fetch_user(user_id)
+            return pn.Text(user.name)
+
+        @pn.component
+        def Screen():
+            return pn.Suspense(
+                Profile(user_id="42"),
+                fallback=pn.ActivityIndicator(),
+            )
+        ```
+    """
+    return Element(SUSPENSE, {"fallback": fallback}, list(children), key=key)

pythonnative/components/text.py

@@ -0,0 +1,291 @@
+"""Text-centric leaf factories: ``Text``, ``Button``, and ``TextInput``."""
+
+from typing import Any, Callable, Literal, Optional
+
+from ..element import Element
+from ..hooks import Ref
+from ..style import (
+    AccessibilityState,
+    AutoCapitalize,
+    Color,
+    KeyboardType,
+    ReturnKeyType,
+    StyleProp,
+)
+from ._base import _flatten_text_spans, _make_element
+
+
+def Text(
+    *parts: Any,
+    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,
+    ref: Optional[Ref] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display a string of text, optionally with styled nested spans.
+
+    Style properties: ``font_size``, ``color``, ``bold``,
+    ``font_weight``, ``font_family``, ``italic``, ``text_align``,
+    ``background_color``, ``max_lines``, ``letter_spacing``,
+    ``line_height``, ``text_decoration`` (``"underline"`` /
+    ``"line_through"``), ``border_radius``, ``border_width``,
+    ``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:
+        *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.
+        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_press: Optional[Callable[[], Any]] = None,
+    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,
+    ref: Optional[Ref] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display a tappable button.
+
+    Style properties: ``color``, ``background_color``, ``font_size``,
+    ``border_radius``, ``border_width``, ``border_color``, ``shadow_*``,
+    ``opacity``, ``transform``, plus the common layout props.
+
+    Buttons get ``accessibility_role="button"`` by default.
+
+    Args:
+        title: Button label.
+        on_press: Callback invoked when the user taps the button.
+        disabled: When ``True``, the button is disabled and cannot be
+            tapped.
+        style: Style dict (or list of dicts).
+        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 ``"Button"``.
+    """
+    return _make_element(
+        "Button",
+        style=style,
+        ref=ref,
+        key=key,
+        title=title,
+        on_press=on_press,
+        disabled=disabled,
+        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 TextInput(
+    *,
+    value: str = "",
+    placeholder: Optional[str] = None,
+    on_change: Optional[Callable[[str], Any]] = None,
+    on_submit: Optional[Callable[[str], Any]] = 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[[], Any]] = None,
+    on_blur: Optional[Callable[[], Any]] = None,
+    selection_color: Optional[Color] = None,
+    text_content_type: Optional[str] = None,
+    style: StyleProp = None,
+    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,
+    ref: Optional[Ref] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Display a text-entry field (single-line by default, or ``multiline``).
+
+    Style properties: ``font_size``, ``color``, ``background_color``,
+    ``border_*``, plus the common layout props.
+
+    Args:
+        value: Current text content (controlled-input pattern).
+        placeholder: Hint shown when ``value`` is empty.
+        on_change: Callback invoked with the new string each keystroke.
+        on_submit: Callback invoked when the user submits (Return /
+            Done / etc.). Receives the final text.
+        secure: When ``True``, characters are masked (use for passwords).
+        multiline: When ``True``, allows multiple lines of input.
+        keyboard_type: One of ``"default"``, ``"email_address"``,
+            ``"number_pad"``, ``"decimal_pad"``, ``"phone_pad"``, ``"url"``.
+        auto_capitalize: One of ``"none"``, ``"sentences"``, ``"words"``,
+            ``"characters"``.
+        auto_correct: Enable/disable autocorrection.
+        auto_focus: Request focus on mount.
+        return_key_type: One of ``"default"``, ``"done"``, ``"go"``,
+            ``"next"``, ``"send"``, ``"search"``.
+        max_length: Maximum number of characters allowed.
+        placeholder_color: Color used for the placeholder string.
+        editable: When ``False``, the field is read-only (still
+            selectable).
+        clear_button: When ``True``, shows a clear ("x") button while
+            editing (iOS ``clearButtonMode``; an inline button on
+            Android).
+        on_focus: Callback invoked when the field gains focus.
+        on_blur: Callback invoked when the field loses focus.
+        selection_color: Cursor / selection highlight color.
+        text_content_type: Semantic content hint for autofill (e.g.
+            ``"username"``, ``"password"``, ``"one_time_code"``).
+        style: Style dict (or list of dicts).
+        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.
+        ref: Optional [`Ref`][pythonnative.Ref] from ``use_ref()``.
+        key: Stable identity for keyed reconciliation.
+
+    Returns:
+        An [`Element`][pythonnative.Element] of type ``"TextInput"``.
+    """
+    return _make_element(
+        "TextInput",
+        style=style,
+        ref=ref,
+        key=key,
+        value=value,
+        placeholder=placeholder,
+        on_change=on_change,
+        on_submit=on_submit,
+        secure=secure or None,
+        multiline=multiline or None,
+        keyboard_type=keyboard_type,
+        auto_capitalize=auto_capitalize,
+        auto_correct=auto_correct,
+        auto_focus=auto_focus or None,
+        return_key_type=return_key_type,
+        max_length=max_length,
+        placeholder_color=placeholder_color,
+        editable=False if editable is False else None,
+        clear_button=clear_button or None,
+        on_focus=on_focus,
+        on_blur=on_blur,
+        selection_color=selection_color,
+        text_content_type=text_content_type,
+        accessibility_label=accessibility_label,
+        accessibility_hint=accessibility_hint,
+        accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
+    )