flet 0.70.0.dev5776__py3-none-any.whl → 0.70.0.dev6145__py3-none-any.whl

flet/components/hooks/use_effect.py

@@ -0,0 +1,104 @@
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from flet.components.hooks.hook import Hook
+from flet.components.utils import current_component
+
+
+@dataclass
+class EffectHook(Hook):
+    setup: Callable[[], Any | Awaitable[Any]]
+    cleanup: Callable[[], Any | Awaitable[Any]] | None = None
+    deps: list[Any] | None = None
+    prev_deps: list[Any] | None = None
+
+    # runtime
+    _setup_task: asyncio.Task | None = None  # last scheduled setup task
+    _cleanup_task: asyncio.Task | None = None  # last scheduled cleanup task
+
+    def cancel(self):
+        if self._setup_task and not self._setup_task.done():
+            self._setup_task.cancel()
+        if self._cleanup_task and not self._cleanup_task.done():
+            self._cleanup_task.cancel()
+
+
+def use_effect(
+    setup: Callable[[], Any | Awaitable[Any]],
+    dependencies: Sequence[Any] | None = None,
+    cleanup: Callable[[], Any | Awaitable[Any]] | None = None,
+):
+    """
+    Perform side effects in function components.
+
+    Args:
+        setup: A function that performs the side effect. It may optionally return
+            a cleanup function.
+        dependencies: If present, the effect is only re-run when one of the dependencies
+            has changed. If absent, the effect is only run on initial render.
+        cleanup: An optional function that cleans up after the effect. It is run
+            before the effect is re-run, and when the component unmounts.
+    """
+    component = current_component()
+    deps = list(dependencies) if dependencies is not None else None
+
+    # get or create effect hook
+    hook = component.use_hook(
+        lambda: EffectHook(
+            component,
+            setup=setup,
+            deps=deps,
+            cleanup=cleanup,
+        )
+    )
+
+    # update effect hook
+    hook.setup = setup
+    hook.prev_deps = hook.deps
+    hook.deps = deps
+    hook.cleanup = cleanup
+
+
+def on_mounted(fn: Callable[[], Any | Awaitable[Any]]) -> None:
+    """
+    Run exactly once after the component mounts.
+
+    Args:
+        fn: A function to run after the component mounts.
+    """
+    use_effect(fn, dependencies=[])
+
+
+def on_unmounted(fn: Callable[[], Any | Awaitable[Any]]) -> None:
+    """
+    Run exactly once when the component unmounts.
+
+    Args:
+        fn: A function to run when the component unmounts.
+    """
+    # No-op setup; only need cleanup to fire on unmount
+    use_effect(lambda: None, dependencies=[], cleanup=fn)
+
+
+def on_updated(
+    fn: Callable[[], Any | Awaitable[Any]], dependencies: Sequence[Any] | None = None
+) -> None:
+    """
+    Run after each post-mount render (or when dependencies change).
+    With dependencies=None this fires every update; with dependencies=[...] only
+    on changes.
+
+    Args:
+        fn: A function to run after each post-mount render (or when dependencies
+            change).
+        dependencies: If present, fn is only run when one of the dependencies has
+            changed. If absent, fn is run after every render.
+    """
+    use_effect(fn, dependencies=dependencies)
+
+
+on_mounted = on_mounted  # alias
+on_unmounted = on_unmounted  # alias
+on_updated = on_updated  # alias

flet/components/hooks/use_memo.py

@@ -0,0 +1,52 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Callable, Generic, TypeVar
+
+from flet.components.hooks.hook import Hook
+from flet.components.utils import current_component, shallow_compare_args
+
+MemoValueT = TypeVar("MemoValueT")
+
+
+@dataclass
+class MemoHook(Hook, Generic[MemoValueT]):
+    value: MemoValueT | None = None
+    prev_deps: list[Any] | None = None
+
+
+def use_memo(
+    calculate_value: Callable[[], MemoValueT], dependencies: Sequence[Any] | None = None
+) -> MemoValueT:
+    """
+    Memoize a computed value between renders.
+
+    Args:
+        calculate_value: A function that computes the value to be memoized.
+        dependencies: If present, the value is only recomputed when one of
+            the dependencies has changed. If absent, the value is only computed
+            on initial render.
+
+    Returns:
+        A memoized value whose identity is stable between renders.
+    """
+    component = current_component()
+
+    def _create() -> MemoHook[MemoValueT]:
+        h = MemoHook[MemoValueT](component)
+        # If deps is None we recompute every render, so no need to preset prev_deps.
+        if dependencies is None:
+            h.value = calculate_value()
+        return h
+
+    hook = component.use_hook(_create)  # type: MemoHook[MemoValueT]
+
+    if dependencies is None:
+        # Always recompute
+        hook.value = calculate_value()
+        return hook.value  # type: ignore[return-value]
+
+    if hook.prev_deps is None or not shallow_compare_args(hook.prev_deps, dependencies):
+        hook.value = calculate_value()
+        hook.prev_deps = list(dependencies)
+
+    return hook.value  # type: ignore[return-value]

flet/components/hooks/use_state.py

@@ -0,0 +1,58 @@
+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

flet/components/memo.py

@@ -0,0 +1,34 @@
+from flet.components.utils import current_renderer
+
+
+def memo(fn):
+    """
+    Lets you skip re-rendering a component when its props are unchanged.
+
+    Example:
+
+    ```python
+    import flet as ft
+
+
+    @ft.component
+    def MyComponent(x, y):
+        return ft.Text(f"x={x}, y={y}")
+
+
+    MemoizedMyComponent = ft.memo(MyComponent)
+
+    flet.run(
+        lambda page: page.render(
+            lambda: MemoizedMyComponent(x=1, y=2),
+        ),
+    )
+    ```
+    """
+
+    def memo_wrapper(*args, **kwargs):
+        r = current_renderer()
+        r.set_memo()
+        return fn(*args, **kwargs)
+
+    return memo_wrapper

flet/components/observable.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import contextlib
+import weakref
+from dataclasses import InitVar, dataclass
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from flet.components.utils import value_equal
+
+if TYPE_CHECKING:
+    from flet.components.component import Component
+
+from flet.components.component_owned import ComponentOwned
+
+Listener = Callable[[Any, Optional[str]], None]  # (sender, field|None)
+
+
+def observable(cls):
+    """
+    Makes a class observable by mixing in [`Observable`][flet.Observable].
+    Can be applied to any class including [`dataclass`][dataclasses.dataclass].
+    For dataclasses, decorator can be placed either above or below
+    the `@dataclass` decorator.
+
+    Example:
+
+    ```python
+    from dataclasses import dataclass
+    import flet as ft
+
+
+    @ft.observable
+    @dataclass
+    class MyDataClass:
+        x: int
+        y: int
+    ```
+    """
+    if Observable in cls.__mro__:
+        return cls
+    # Build a new class whose MRO is (Observable, cls)
+    ns = dict(cls.__dict__)
+    # Defensive: avoid carrying these special slots over
+    ns.pop("__dict__", None)
+    ns.pop("__weakref__", None)
+
+    Mixed = type(cls.__name__, (Observable, cls), ns)
+    Mixed.__module__ = cls.__module__
+    Mixed.__qualname__ = cls.__qualname__
+    return Mixed
+
+
+@dataclass
+class ObservableSubscription(ComponentOwned):
+    observable: InitVar[Observable]
+
+    def __post_init__(self, owner: Component, observable: Observable) -> None:
+        super().__post_init__(owner)
+        self.__disposer = observable.subscribe(self.__on_change)
+
+    def dispose(self):
+        if callable(self.__disposer):
+            self.__disposer()
+            self.__disposer = None
+
+    def __on_change(self, _sender, _field):
+        if self.component:
+            self.component._schedule_update()
+
+
+class Observable:
+    """
+    Mixin: notifies when fields change; auto-wraps lists/dicts to be observable.
+
+    Example:
+
+    ```python
+    import flet as ft
+    from dataclasses import dataclass
+
+
+    @ft.observable
+    @dataclass
+    class MyDataClass:
+        x: int
+        y: int
+
+
+    obj = MyDataClass(1, 2)
+
+
+    def listener(sender, field):
+        print(f"Changed: {field} in {sender}")
+
+
+    obj.subscribe(listener)
+    obj.x = 3
+    obj.y = 4
+    ```
+    """
+
+    __version__ = 0  # optional version counter
+
+    # listeners store (lazy)
+    @property
+    def __listeners(self):
+        storage_name = "_Observable__listeners_storage"
+        try:
+            return object.__getattribute__(self, storage_name)
+        except AttributeError:
+            ws = weakref.WeakSet()
+            object.__setattr__(self, storage_name, ws)
+            return ws
+
+    # subscribe / notify
+    def subscribe(self, fn: Listener) -> Callable[[], None]:
+        self.__listeners.add(fn)
+
+        def dispose():
+            with contextlib.suppress(KeyError):
+                self.__listeners.remove(fn)
+
+        return dispose
+
+    def _notify(self, field: str | None):
+        self.__version__ += 1
+        for fn in list(self.__listeners):
+            fn(self, field)
+
+    # collection wrapping
+    def _wrap_if_collection(self, name: str, value: Any) -> Any:
+        if isinstance(value, list) and not isinstance(value, ObservableList):
+            return ObservableList(self, name, value)
+        if isinstance(value, dict) and not isinstance(value, ObservableDict):
+            return ObservableDict(self, name, value)
+        return value
+
+    # attribute interception
+    def __setattr__(self, name: str, value: Any):
+        if name.startswith("_"):  # private/internal, don't notify
+            object.__setattr__(self, name, value)
+            return
+        value = self._wrap_if_collection(name, value)
+        had = hasattr(self, name)
+        old = object.__getattribute__(self, name) if had else None
+        if not value_equal(old, value):
+            object.__setattr__(self, name, value)
+            self._notify(name)
+
+    def __delattr__(self, name: str):
+        existed = hasattr(self, name)
+        object.__delattr__(self, name)
+        if existed:
+            self._notify(name)
+
+    def __repr__(self):
+        return f"{super().__repr__()} (version={self.__version__})"
+
+
+# Observable collections -----------------------------------------
+
+
+class ObservableList(list):
+    __slots__ = ("_owner_ref", "_field")
+
+    def __init__(self, owner: Observable, field: str, iterable=()):
+        super().__init__(iterable)
+        self._owner_ref = weakref.ref(owner)
+        self._field = field
+
+    def _touch(self):
+        owner = self._owner_ref()
+        if owner:
+            owner._notify(self._field)
+
+    def _wrap(self, v):
+        owner = self._owner_ref()
+        return owner._wrap_if_collection(self._field, v) if owner else v
+
+    def append(self, x):
+        super().append(self._wrap(x))
+        self._touch()
+
+    def extend(self, it):
+        super().extend(self._wrap(v) for v in it)
+        self._touch()
+
+    def insert(self, i, x):
+        super().insert(i, self._wrap(x))
+        self._touch()
+
+    def remove(self, x):
+        super().remove(x)
+        self._touch()
+
+    def clear(self):
+        super().clear()
+        self._touch()
+
+    def sort(self, *a, **k):
+        super().sort(*a, **k)
+        self._touch()
+
+    def reverse(self):
+        super().reverse()
+        self._touch()
+
+    def pop(self, i=-1):
+        v = super().pop(i)
+        self._touch()
+        return v
+
+    def __setitem__(self, i, v):
+        super().__setitem__(i, self._wrap(v))
+        self._touch()
+
+    def __delitem__(self, i):
+        super().__delitem__(i)
+        self._touch()
+
+
+class ObservableDict(dict):
+    __slots__ = ("_owner_ref", "_field")
+
+    def __init__(self, owner: Observable, field: str, mapping=()):
+        super().__init__(mapping)
+        self._owner_ref = weakref.ref(owner)
+        self._field = field
+
+    def _touch(self):
+        owner = self._owner_ref()
+        if owner:
+            owner._notify(self._field)
+
+    def _wrap(self, v):
+        owner = self._owner_ref()
+        return owner._wrap_if_collection(self._field, v) if owner else v
+
+    def __setitem__(self, k, v):
+        super().__setitem__(k, self._wrap(v))
+        self._touch()
+
+    def __delitem__(self, k):
+        super().__delitem__(k)
+        self._touch()
+
+    def clear(self):
+        super().clear()
+        self._touch()
+
+    def update(self, *a, **k):
+        super().update(*a, **{kk: self._wrap(vv) for kk, vv in k.items()})
+        self._touch()
+
+    def pop(self, k, *d):
+        v = super().pop(k, *d)
+        self._touch()
+        return v
+
+    def popitem(self):
+        kv = super().popitem()
+        self._touch()
+        return kv
+
+    def setdefault(self, k, d=None):
+        if k not in self:
+            super().__setitem__(k, self._wrap(d))
+            self._touch()
+        return dict.__getitem__(self, k)

flet/components/public_utils.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+from flet.components.component import Component
+
+
+def unwrap_component(c: Any):
+    p = c
+    while isinstance(p, Component):
+        p = p._b
+    return p

flet/components/utils.py

@@ -0,0 +1,85 @@
+import contextvars
+import math
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from flet.components.component import Component, Renderer
+
+
+_CURRENT_RENDERER: "contextvars.ContextVar[Renderer | None]" = contextvars.ContextVar(
+    "CURRENT_RENDERER", default=None
+)
+
+
+def current_renderer() -> "Renderer":
+    r = _CURRENT_RENDERER.get()
+    if r is None:
+        raise RuntimeError(
+            "No current renderer is set. Call via Renderer.render(...) "
+            "or Renderer.with_context(...)."
+        )
+    return r
+
+
+def current_component() -> "Component":
+    r = current_renderer()
+    if not r._render_stack:
+        raise RuntimeError("Hooks must be called inside a component render.")
+    return r._render_stack[-1]
+
+
+def value_equal(a, b) -> bool:
+    # Fast path
+    if a is b:
+        return True
+    # Handle normal equality
+    try:
+        if a == b:
+            return True
+    except Exception:
+        pass
+    # Treat NaN == NaN as equal (like JS Object.is)
+    return (
+        isinstance(a, float)
+        and isinstance(b, float)
+        and math.isnan(a)
+        and math.isnan(b)
+    )
+
+
+def shallow_compare_args(
+    prev_args: Sequence[Any],
+    args: Sequence[Any],
+) -> bool:
+    if prev_args is args:
+        return True
+    if len(prev_args) != len(args):
+        return False
+    return all(not (a is not b and a != b) for a, b in zip(prev_args, args))
+
+
+def shallow_compare_kwargs(
+    prev_kwargs: dict[str, Any],
+    kwargs: dict[str, Any],
+) -> bool:
+    if prev_kwargs is kwargs:
+        return True
+    if prev_kwargs.keys() != kwargs.keys():
+        return False
+    for k in prev_kwargs:
+        a, b = prev_kwargs[k], kwargs[k]
+        if a is not b and a != b:
+            return False
+    return True
+
+
+def shallow_compare_args_and_kwargs(
+    prev_args: tuple[Any, ...],
+    prev_kwargs: dict[str, Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> bool:
+    return shallow_compare_args(prev_args, args) and shallow_compare_kwargs(
+        prev_kwargs, kwargs
+    )