flet 0.70.0.dev6370__tar.gz → 0.70.0.dev6412__tar.gz

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet
-Version: 0.70.0.dev6370
+Version: 0.70.0.dev6412
 Summary: Flet for Python - easily build interactive multi-platform apps in Python
 Author-email: "Appveyor Systems Inc." <hello@flet.dev>
 License-Expression: Apache-2.0

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flet"
-version = "0.70.0.dev6370"
+version = "0.70.0.dev6412"
 description = "Flet for Python - easily build interactive multi-platform apps in Python"
 authors = [{name = "Appveyor Systems Inc.", email = "hello@flet.dev"}]
 license = "Apache-2.0"

flet-0.70.0.dev6412/src/flet/components/hooks/use_state.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from flet.components.hooks.hook import Hook
+from flet.components.observable import Observable, ObservableSubscription
+from flet.components.utils import current_component
+
+StateT = TypeVar("StateT")
+Updater = Callable[[StateT], StateT]
+
+
+@dataclass
+class StateHook(Hook):
+    value: Any
+    subscription: ObservableSubscription | None = None
+    version: int = 0
+
+
+def use_state(
+    initial: StateT | Callable[[], StateT],
+) -> tuple[StateT, Callable[[StateT | Updater], None]]:
+    """
+    Adds state to a function component, similar to React's useState().
+
+    The returned setter accepts either:
+      - a new value, or
+      - a function receiving the previous state and returning the next one.
+
+    Args:
+        initial: Initial state value or a function returning it.
+
+    Returns:
+        (value, set_value) tuple.
+    """
+    component = current_component()
+    hook = component.use_hook(
+        lambda: StateHook(
+            component,
+            initial() if callable(initial) else initial,
+        )
+    )
+
+    def update_subscription(h: StateHook):
+        # Detach previous subscription if any
+        if h.subscription:
+            component._detach_observable_subscription(h.subscription)
+            h.subscription = None
+
+        # Attach new subscription if value is Observable
+        if isinstance(h.value, Observable):
+            h.subscription = component._attach_observable_subscription(h.value)
+
+    update_subscription(hook)
+
+    def set_state(new_value_or_fn: StateT | Updater):
+        """
+        Update the state value.
+
+        Can be called with either:
+          - a direct new value, or
+          - a function that takes the current value and returns the next one.
+        """
+        # Compute next value
+        new_value = (
+            new_value_or_fn(hook.value)
+            if callable(new_value_or_fn)
+            else new_value_or_fn
+        )
+
+        # Only trigger update if value changed (shallow equality)
+        if new_value != hook.value:
+            hook.value = new_value
+            update_subscription(hook)
+            hook.version += 1
+            if hook.component:
+                hook.component._schedule_update()
+
+    return hook.value, set_state

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/core/stack.py

@@ -31,6 +31,33 @@ class Stack(LayoutControl, AdaptiveControl):
     Stack is also useful if you want to implement implicit animations
     (https://flet.dev/docs/guides/python/animations/) that require knowing absolute
     position of a target value.
+
+    ```python
+    ft.Stack(
+            width=300,
+            height=300,
+            controls=[
+                ft.Image(
+                    src="https://picsum.photos/300/300",
+                    width=300,
+                    height=300,
+                    fit=ft.BoxFit.CONTAIN,
+                ),
+                ft.Row(
+                    alignment=ft.MainAxisAlignment.CENTER,
+                    controls=[
+                        ft.Text(
+                            value="Image title",
+                            color=ft.Colors.SURFACE_TINT,
+                            size=40,
+                            weight=ft.FontWeight.BOLD,
+                            opacity=0.5,
+                        )
+                    ],
+                ),
+            ],
+        )
+    ```
     """
 
     controls: list[Control] = field(default_factory=list)

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/auto_complete.py

@@ -1,9 +1,9 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
+from flet import LayoutControl
 from flet.controls.base_control import control
-from flet.controls.control import Control
-from flet.controls.control_event import Event, EventHandler
+from flet.controls.control_event import ControlEventHandler, Event, EventHandler
 from flet.controls.types import Number
 
 __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
@@ -11,22 +11,45 @@ __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
 
 @dataclass
 class AutoCompleteSuggestion:
+    """
+    Represents a suggestion item for the [`AutoComplete`][flet.] control.
+    """
+
     key: str
+    """A unique identifier or value used for filtering and selection."""
+
     value: str
+    """The display text shown to the user."""
 
 
 @dataclass
 class AutoCompleteSelectEvent(Event["AutoComplete"]):
+    """Event representing the selection of a suggestion in the AutoComplete control."""
+
+    index: int
+    """
+    The index of the selected suggestion from the corresponding
+    [`AutoComplete.suggestions`][flet.] list.
+    """
+
     selection: AutoCompleteSuggestion
+    """The selected suggestion."""
 
 
 @control("AutoComplete")
-class AutoComplete(Control):
+class AutoComplete(LayoutControl):
     """
     Helps the user make a selection by entering some text and choosing from among a
     list of displayed options.
     """
 
+    value: str = ""
+    """
+    Current text displayed in the input field.
+
+    This value reflects user input even if it does not match any provided suggestion.
+    """
+
     suggestions: list[AutoCompleteSuggestion] = field(default_factory=list)
     """
     A list of [`AutoCompleteSuggestion`][flet.]
@@ -53,7 +76,19 @@ class AutoComplete(Control):
     Called when a suggestion is selected.
     """
 
+    on_change: Optional[ControlEventHandler["AutoComplete"]] = None
+    """
+    Called when the input text changes.
+    """
+
     @property
-    def selected_index(self):
-        # TODO: check availability of _selected_index + a default if not yet available
-        return self._selected_index
+    def selected_index(self) -> Optional[int]:
+        """
+        The index of the (last) selected suggestion.
+
+        It is `None` until a suggestion has been selected from the UI.
+
+        Note:
+            This property is read-only.
+        """
+        return getattr(self, "_selected_index", None)

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/menu_item_button.py

@@ -80,7 +80,7 @@ class MenuItemButton(LayoutControl):
 
     on_click: Optional[ControlEventHandler["MenuItemButton"]] = None
     """
-    Called when the button is clicked.
+    Called when the button is clicked.If not defined the button will be disabled.
     """
 
     on_hover: Optional[ControlEventHandler["MenuItemButton"]] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/submenu_button.py

@@ -19,6 +19,25 @@ class SubmenuButton(LayoutControl):
     A menu button that displays a cascading menu.
 
     Typically used in a [`MenuBar`][flet.] control.
+
+    ```python
+    ft.SubmenuButton(
+        content=ft.Text("Choose text style"),
+        key="smbutton",
+        expand=True,
+        menu_style=ft.MenuStyle(
+            alignment=ft.Alignment.BOTTOM_LEFT, side=ft.BorderSide(1)
+        ),
+        controls=[
+            ft.MenuItemButton(
+                content=ft.Text("Underlined"),
+                on_click=lambda e: print(f"{e.control.content.value}.on_click")
+            ),
+            ft.MenuItemButton(...),
+            ...
+        ]
+    )
+    ```
     """
 
     content: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/switch.py

@@ -26,6 +26,11 @@ class Switch(LayoutControl, AdaptiveControl):
     two mutually exclusive options.
 
     For example, "On/Off", "Show/Hide".
+
+    ```python
+        ft.Switch(label="Unchecked switch", value=False)
+        ft.Switch(label="Disabled switch", disabled=True)
+    ```
     """
 
     label: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/text_button.py

@@ -22,6 +22,14 @@ class TextButton(LayoutControl, AdaptiveControl):
     Text buttons are used for the lowest priority actions, especially when presenting
     multiple options. Text buttons can be placed on a variety of backgrounds. Until the
     button is interacted with, its container isn’t visible.
+
+    ```python
+    ft.TextButton(
+            content="Text Button",
+            icon=ft.Icons.STAR_BORDER,
+            icon_color=ft.Colors.BLUE_300,
+        )
+    ```
     """
 
     content: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/controls/material/time_picker.py

@@ -38,6 +38,14 @@ class TimePicker(DialogControl):
 
     Depending on the `time_picker_entry_mode`, it will show either a Dial or
     an Input (hour and minute text fields) for picking a time.
+
+    ```python
+    ft.TimePicker(
+        value=time(1, 2),
+        time_picker_entry_mode=ft.TimePickerEntryMode.INPUT_ONLY,
+        open=True,
+    )
+    ```
     """
 
     value: Optional[time] = field(default_factory=lambda: datetime.now().time())

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet/version.py

@@ -10,7 +10,7 @@ from flet.utils import is_mobile, is_windows, which
 DEFAULT_VERSION = "0.1.0"
 
 # will be replaced by CI
-version = "0.70.0.dev6370"
+version = "0.70.0.dev6412"
 
 
 def update_version():

{flet-0.70.0.dev6370 → flet-0.70.0.dev6412}/src/flet.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet
-Version: 0.70.0.dev6370
+Version: 0.70.0.dev6412
 Summary: Flet for Python - easily build interactive multi-platform apps in Python
 Author-email: "Appveyor Systems Inc." <hello@flet.dev>
 License-Expression: Apache-2.0

flet-0.70.0.dev6370/src/flet/components/hooks/use_state.py

@@ -1,58 +0,0 @@
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Any, TypeVar
-
-from flet.components.hooks.hook import Hook
-from flet.components.observable import Observable, ObservableSubscription
-from flet.components.utils import current_component
-
-
-@dataclass
-class StateHook(Hook):
-    value: Any
-    subscription: ObservableSubscription | None = None
-    version: int = 0
-
-
-StateT = TypeVar("StateT")
-
-
-def use_state(
-    initial: StateT | Callable[[], StateT],
-) -> tuple[StateT, Callable[[StateT], None]]:
-    """
-    Add state to function components.
-
-    Args:
-        initial: Initial state value or a function that returns the initial state value.
-
-    Returns:
-        A tuple of the current state value and a function to update it.
-    """
-    component = current_component()
-    hook = component.use_hook(
-        lambda: StateHook(
-            component,
-            initial() if callable(initial) else initial,
-        )
-    )
-
-    def update_subscription(hook: StateHook):
-        if hook.subscription:
-            component._detach_observable_subscription(hook.subscription)
-            hook.subscription = None
-        if isinstance(hook.value, Observable):
-            hook.subscription = component._attach_observable_subscription(hook.value)
-
-    update_subscription(hook)
-
-    def set_state(new_value: Any):
-        # shallow equality; swap to "is" or custom comparator if needed
-        if new_value != hook.value:
-            hook.value = new_value
-            update_subscription(hook)
-            hook.version += 1
-            if hook.component:
-                hook.component._schedule_update()
-
-    return hook.value, set_state