pythonnative 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

pythonnative/components.py

@@ -4,52 +4,29 @@ Each function returns an :class:`Element` describing a native UI widget.
 These are pure data — no native views are created until the reconciler
 mounts the element tree.
 
-Layout properties (``width``, ``height``, ``flex``, ``margin``,
-``min_width``, ``max_width``, ``min_height``, ``max_height``,
-``align_self``) are supported by all components.
-"""
-
-from typing import Any, Callable, Dict, List, Optional, Union
-
-from .element import Element
+All visual and layout properties are passed via the ``style`` parameter,
+which accepts a dict or a list of dicts (later entries override earlier).
 
-# ======================================================================
-# Shared helpers
-# ======================================================================
+Layout properties supported by all components::
 
-PaddingValue = Union[int, float, Dict[str, Union[int, float]]]
-MarginValue = Union[int, float, Dict[str, Union[int, float]]]
+    width, height, flex, flex_grow, flex_shrink, margin,
+    min_width, max_width, min_height, max_height, align_self
 
+Flex container properties (View / Column / Row)::
 
-def _filter_none(**kwargs: Any) -> Dict[str, Any]:
-    """Return *kwargs* with ``None``-valued entries removed."""
-    return {k: v for k, v in kwargs.items() if v is not None}
+    flex_direction, justify_content, align_items, overflow,
+    spacing, padding
 
+``View`` is the universal flex container (like React Native's ``View``).
+It defaults to ``flex_direction: "column"``.  ``Column`` and ``Row``
+are convenience wrappers that fix the direction to ``"column"`` and
+``"row"`` respectively.
+"""
 
-def _layout_props(
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
-) -> Dict[str, Any]:
-    """Collect common layout props into a dict (excluding Nones)."""
-    return _filter_none(
-        width=width,
-        height=height,
-        flex=flex,
-        margin=margin,
-        min_width=min_width,
-        max_width=max_width,
-        min_height=min_height,
-        max_height=max_height,
-        align_self=align_self,
-    )
+from typing import Any, Callable, Dict, List, Optional
 
+from .element import Element
+from .style import StyleValue, resolve_style
 
 # ======================================================================
 # Leaf components
@@ -59,46 +36,16 @@ def _layout_props(
 def Text(
     text: str = "",
     *,
-    font_size: Optional[float] = None,
-    color: Optional[str] = None,
-    bold: bool = False,
-    text_align: Optional[str] = None,
-    background_color: Optional[str] = None,
-    max_lines: Optional[int] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Display text."""
-    props = _filter_none(
-        text=text,
-        font_size=font_size,
-        color=color,
-        bold=bold or None,
-        text_align=text_align,
-        background_color=background_color,
-        max_lines=max_lines,
-    )
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    """Display text.
+
+    Style properties: ``font_size``, ``color``, ``bold``, ``text_align``,
+    ``background_color``, ``max_lines``, plus common layout props.
+    """
+    props: Dict[str, Any] = {"text": text}
+    props.update(resolve_style(style))
     return Element("Text", props, [], key=key)
 
 
@@ -106,46 +53,21 @@ def Button(
     title: str = "",
     *,
     on_click: Optional[Callable[[], None]] = None,
-    color: Optional[str] = None,
-    background_color: Optional[str] = None,
-    font_size: Optional[float] = None,
     enabled: bool = True,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Create a tappable button."""
+    """Create a tappable button.
+
+    Style properties: ``color``, ``background_color``, ``font_size``,
+    plus common layout props.
+    """
     props: Dict[str, Any] = {"title": title}
     if on_click is not None:
         props["on_click"] = on_click
-    if color is not None:
-        props["color"] = color
-    if background_color is not None:
-        props["background_color"] = background_color
-    if font_size is not None:
-        props["font_size"] = font_size
     if not enabled:
         props["enabled"] = False
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    props.update(resolve_style(style))
     return Element("Button", props, [], key=key)
 
 
@@ -155,21 +77,14 @@ def TextInput(
     placeholder: str = "",
     on_change: Optional[Callable[[str], None]] = None,
     secure: bool = False,
-    font_size: Optional[float] = None,
-    color: Optional[str] = None,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Create a single-line text entry field."""
+    """Create a single-line text entry field.
+
+    Style properties: ``font_size``, ``color``, ``background_color``,
+    plus common layout props.
+    """
     props: Dict[str, Any] = {"value": value}
     if placeholder:
         props["placeholder"] = placeholder
@@ -177,63 +92,27 @@ def TextInput(
         props["on_change"] = on_change
     if secure:
         props["secure"] = True
-    if font_size is not None:
-        props["font_size"] = font_size
-    if color is not None:
-        props["color"] = color
-    if background_color is not None:
-        props["background_color"] = background_color
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    props.update(resolve_style(style))
     return Element("TextInput", props, [], key=key)
 
 
 def Image(
     source: str = "",
     *,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
     scale_type: Optional[str] = None,
-    background_color: Optional[str] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Display an image from a resource path or URL."""
-    props = _filter_none(
-        source=source or None,
-        width=width,
-        height=height,
-        scale_type=scale_type,
-        background_color=background_color,
-    )
-    props.update(
-        _layout_props(
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    """Display an image from a resource path or URL.
+
+    Style properties: ``background_color``, plus common layout props.
+    """
+    props: Dict[str, Any] = {}
+    if source:
+        props["source"] = source
+    if scale_type is not None:
+        props["scale_type"] = scale_type
+    props.update(resolve_style(style))
     return Element("Image", props, [], key=key)
 
 
@@ -241,68 +120,52 @@ def Switch(
     *,
     value: bool = False,
     on_change: Optional[Callable[[bool], None]] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Create a toggle switch."""
     props: Dict[str, Any] = {"value": value}
     if on_change is not None:
         props["on_change"] = on_change
-    props.update(_layout_props(width=width, height=height, flex=flex, margin=margin, align_self=align_self))
+    props.update(resolve_style(style))
     return Element("Switch", props, [], key=key)
 
 
 def ProgressBar(
     *,
     value: float = 0.0,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Show determinate progress (0.0 – 1.0)."""
-    props = _filter_none(value=value, background_color=background_color)
-    props.update(_layout_props(width=width, height=height, flex=flex, margin=margin, align_self=align_self))
+    props: Dict[str, Any] = {"value": value}
+    props.update(resolve_style(style))
     return Element("ProgressBar", props, [], key=key)
 
 
 def ActivityIndicator(
     *,
     animating: bool = True,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Show an indeterminate loading spinner."""
     props: Dict[str, Any] = {"animating": animating}
-    props.update(_layout_props(width=width, height=height, margin=margin, align_self=align_self))
+    props.update(resolve_style(style))
     return Element("ActivityIndicator", props, [], key=key)
 
 
 def WebView(
     *,
     url: str = "",
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Embed web content."""
     props: Dict[str, Any] = {}
     if url:
         props["url"] = url
-    props.update(_layout_props(width=width, height=height, flex=flex, margin=margin, align_self=align_self))
+    props.update(resolve_style(style))
     return Element("WebView", props, [], key=key)
 
 
@@ -312,158 +175,147 @@ def Spacer(
     flex: Optional[float] = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Insert empty space with an optional fixed size."""
-    props = _filter_none(size=size, flex=flex)
+    """Insert empty space with an optional fixed size or flex weight."""
+    props: Dict[str, Any] = {}
+    if size is not None:
+        props["size"] = size
+    if flex is not None:
+        props["flex"] = flex
     return Element("Spacer", props, [], key=key)
 
 
+def Slider(
+    *,
+    value: float = 0.0,
+    min_value: float = 0.0,
+    max_value: float = 1.0,
+    on_change: Optional[Callable[[float], None]] = None,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Continuous value slider."""
+    props: Dict[str, Any] = {
+        "value": value,
+        "min_value": min_value,
+        "max_value": max_value,
+    }
+    if on_change is not None:
+        props["on_change"] = on_change
+    props.update(resolve_style(style))
+    return Element("Slider", props, [], key=key)
+
+
 # ======================================================================
 # Container components
 # ======================================================================
 
 
+def View(
+    *children: Element,
+    style: StyleValue = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Universal flex container (like React Native's ``View``).
+
+    Defaults to ``flex_direction: "column"``.  Override via ``style``::
+
+        pn.View(child_a, child_b, style={"flex_direction": "row"})
+
+    Flex container properties (inside ``style``):
+
+    - ``flex_direction`` — ``"column"`` (default), ``"row"``,
+      ``"column_reverse"``, ``"row_reverse"``
+    - ``justify_content`` — main-axis distribution:
+      ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+      ``"space_between"``, ``"space_around"``, ``"space_evenly"``
+    - ``align_items`` — cross-axis alignment:
+      ``"stretch"`` (default), ``"flex_start"``, ``"center"``,
+      ``"flex_end"``
+    - ``overflow`` — ``"visible"`` (default) or ``"hidden"``
+    - ``spacing``, ``padding``, ``background_color``
+    """
+    props: Dict[str, Any] = {"flex_direction": "column"}
+    props.update(resolve_style(style))
+    return Element("View", props, list(children), key=key)
+
+
 def Column(
     *children: Element,
-    spacing: float = 0,
-    padding: Optional[PaddingValue] = None,
-    alignment: Optional[str] = None,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Arrange children vertically."""
-    props = _filter_none(
-        spacing=spacing or None,
-        padding=padding,
-        alignment=alignment,
-        background_color=background_color,
-    )
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    """Arrange children vertically (``flex_direction: "column"``).
+
+    Convenience wrapper around :func:`View`.  The direction is fixed;
+    use :func:`View` directly if you need ``flex_direction: "row"``.
+
+    Style properties: ``spacing``, ``padding``, ``align_items``,
+    ``justify_content``, ``background_color``, ``overflow``,
+    plus common layout props.
+
+    ``align_items`` controls cross-axis (horizontal) alignment:
+    ``"stretch"`` (default), ``"flex_start"``/``"leading"``,
+    ``"center"``, ``"flex_end"``/``"trailing"``.
+
+    ``justify_content`` controls main-axis (vertical) distribution:
+    ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+    ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
+    """
+    props: Dict[str, Any] = {"flex_direction": "column"}
+    props.update(resolve_style(style))
+    props["flex_direction"] = "column"
     return Element("Column", props, list(children), key=key)
 
 
 def Row(
     *children: Element,
-    spacing: float = 0,
-    padding: Optional[PaddingValue] = None,
-    alignment: Optional[str] = None,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
-    """Arrange children horizontally."""
-    props = _filter_none(
-        spacing=spacing or None,
-        padding=padding,
-        alignment=alignment,
-        background_color=background_color,
-    )
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
+    """Arrange children horizontally (``flex_direction: "row"``).
+
+    Convenience wrapper around :func:`View`.  The direction is fixed;
+    use :func:`View` directly if you need ``flex_direction: "column"``.
+
+    Style properties: ``spacing``, ``padding``, ``align_items``,
+    ``justify_content``, ``background_color``, ``overflow``,
+    plus common layout props.
+
+    ``align_items`` controls cross-axis (vertical) alignment:
+    ``"stretch"`` (default), ``"flex_start"``/``"top"``,
+    ``"center"``, ``"flex_end"``/``"bottom"``.
+
+    ``justify_content`` controls main-axis (horizontal) distribution:
+    ``"flex_start"`` (default), ``"center"``, ``"flex_end"``,
+    ``"space_between"``, ``"space_around"``, ``"space_evenly"``.
+    """
+    props: Dict[str, Any] = {"flex_direction": "row"}
+    props.update(resolve_style(style))
+    props["flex_direction"] = "row"
     return Element("Row", props, list(children), key=key)
 
 
 def ScrollView(
     child: Optional[Element] = None,
     *,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Wrap a single child in a scrollable container."""
     children = [child] if child is not None else []
-    props = _filter_none(background_color=background_color)
-    props.update(_layout_props(width=width, height=height, flex=flex, margin=margin, align_self=align_self))
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
     return Element("ScrollView", props, children, key=key)
 
 
-def View(
-    *children: Element,
-    background_color: Optional[str] = None,
-    padding: Optional[PaddingValue] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    min_width: Optional[float] = None,
-    max_width: Optional[float] = None,
-    min_height: Optional[float] = None,
-    max_height: Optional[float] = None,
-    align_self: Optional[str] = None,
-    key: Optional[str] = None,
-) -> Element:
-    """Generic container view (``UIView`` / ``android.view.View``)."""
-    props = _filter_none(
-        background_color=background_color,
-        padding=padding,
-    )
-    props.update(
-        _layout_props(
-            width=width,
-            height=height,
-            flex=flex,
-            margin=margin,
-            min_width=min_width,
-            max_width=max_width,
-            min_height=min_height,
-            max_height=max_height,
-            align_self=align_self,
-        )
-    )
-    return Element("View", props, list(children), key=key)
-
-
 def SafeAreaView(
     *children: Element,
-    background_color: Optional[str] = None,
-    padding: Optional[PaddingValue] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Container that respects safe area insets (notch, status bar)."""
-    props = _filter_none(background_color=background_color, padding=padding)
+    props: Dict[str, Any] = {}
+    props.update(resolve_style(style))
     return Element("SafeAreaView", props, list(children), key=key)
 
 
@@ -472,7 +324,7 @@ def Modal(
     visible: bool = False,
     on_dismiss: Optional[Callable[[], None]] = None,
     title: Optional[str] = None,
-    background_color: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Overlay modal dialog.
@@ -484,34 +336,10 @@ def Modal(
         props["on_dismiss"] = on_dismiss
     if title is not None:
         props["title"] = title
-    if background_color is not None:
-        props["background_color"] = background_color
+    props.update(resolve_style(style))
     return Element("Modal", props, list(children), key=key)
 
 
-def Slider(
-    *,
-    value: float = 0.0,
-    min_value: float = 0.0,
-    max_value: float = 1.0,
-    on_change: Optional[Callable[[float], None]] = None,
-    width: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
-    key: Optional[str] = None,
-) -> Element:
-    """Continuous value slider."""
-    props: Dict[str, Any] = {
-        "value": value,
-        "min_value": min_value,
-        "max_value": max_value,
-    }
-    if on_change is not None:
-        props["on_change"] = on_change
-    props.update(_layout_props(width=width, margin=margin, align_self=align_self))
-    return Element("Slider", props, [], key=key)
-
-
 def Pressable(
     child: Optional[Element] = None,
     *,
@@ -529,26 +357,43 @@ def Pressable(
     return Element("Pressable", props, children, key=key)
 
 
+def ErrorBoundary(
+    child: Optional[Element] = None,
+    *,
+    fallback: Optional[Any] = None,
+    key: Optional[str] = None,
+) -> Element:
+    """Catch render errors in *child* and display *fallback* instead.
+
+    *fallback* may be an ``Element`` or a callable that receives the
+    exception and returns an ``Element``::
+
+        pn.ErrorBoundary(
+            MyRiskyComponent(),
+            fallback=lambda err: pn.Text(f"Error: {err}"),
+        )
+    """
+    props: Dict[str, Any] = {}
+    if fallback is not None:
+        props["__fallback__"] = fallback
+    children = [child] if child is not None else []
+    return Element("__ErrorBoundary__", props, children, key=key)
+
+
 def FlatList(
     *,
     data: Optional[List[Any]] = None,
     render_item: Optional[Callable[[Any, int], Element]] = None,
     key_extractor: Optional[Callable[[Any, int], str]] = None,
     separator_height: float = 0,
-    background_color: Optional[str] = None,
-    width: Optional[float] = None,
-    height: Optional[float] = None,
-    flex: Optional[float] = None,
-    margin: Optional[MarginValue] = None,
-    align_self: Optional[str] = None,
+    style: StyleValue = None,
     key: Optional[str] = None,
 ) -> Element:
     """Scrollable list that renders items from *data* using *render_item*.
 
     Each item is rendered by calling ``render_item(item, index)``.  If
     ``key_extractor`` is provided, it is called as ``key_extractor(item, index)``
-    to produce a stable key for each child element.  This enables the
-    reconciler to preserve widget state across data changes.
+    to produce a stable key for each child element.
     """
     items: List[Element] = []
     for i, item in enumerate(data or []):
@@ -557,7 +402,7 @@ def FlatList(
             el = Element(el.type, el.props, el.children, key=key_extractor(item, i))
         items.append(el)
 
-    inner = Column(*items, spacing=separator_height)
-    sv_props = _filter_none(background_color=background_color)
-    sv_props.update(_layout_props(width=width, height=height, flex=flex, margin=margin, align_self=align_self))
+    inner = Column(*items, style={"spacing": separator_height} if separator_height else None)
+    sv_props: Dict[str, Any] = {}
+    sv_props.update(resolve_style(style))
     return Element("ScrollView", sv_props, [inner], key=key)