annie.pages.utils
=================

.. py:module:: annie.pages.utils

.. autoapi-nested-parse::

   Shared UI helpers used by multiple page modules (UI).



Attributes
----------

.. autoapisummary::

   annie.pages.utils.DEBOUNCE


Functions
---------

.. autoapisummary::

   annie.pages.utils.render_embed_ttl
   annie.pages.utils.notify_detached
   annie.pages.utils.unembed_after_idle


Module Contents
---------------

.. py:data:: DEBOUNCE
   :value: 'debounce=300'


   apply the value 300 ms after the last keystroke.

   :type: Quasar prop for typed filter inputs

.. py:function:: render_embed_ttl() -> float

   Idle-revert delay for an embedded *rendered* clip.

   Capped at the temp-dir sweep TTL so a rendered clip's ``ui.video`` always reverts
   to its placeholder no later than the periodic sweep deletes the underlying file —
   the element never points at a clip that has been reclaimed from disk.


.. py:function:: notify_detached(client: nicegui.Client, message: str, *, color: str) -> None

   Toast from a handler that tore down the slot it was invoked in.

   ``ui.notify`` resolves its client through the slot the handler runs in, which
   NiceGUI takes from the sender's **parent** element. A handler that deletes its
   own row — or refreshes the container holding its button — drops the last
   reference to that parent, so a later ``ui.notify`` dies with "the parent element
   this slot belongs to has been deleted".

   Re-entering ``client`` lands in :attr:`nicegui.Client.content`, which outlives
   any refresh, so the toast survives the teardown that caused it.

   :param client: The client captured *before* the teardown (``context.client``).
   :param message: The toast text.
   :param color: The toast colour.


.. py:function:: unembed_after_idle(box: nicegui.ui.element, restore: collections.abc.Callable[[], None], *, ttl: float | None = None) -> None

   Swap an embedded clip back to its placeholder once it has sat idle.

   An embedded ``ui.video`` keeps its clip buffered in the browser tab (and its
   element alive server-side) for as long as the row is on the page. A reviewer
   who plays a dozen clips while scrolling never gets that memory back. So each
   embed schedules its own reversal: after ``ttl`` seconds, ``restore`` rebuilds the
   cheap placeholder and the clip is dropped.

   The wait runs via :func:`annie.pages.lazy.schedule`, so a row refreshed away
   mid-wait has no parent slot to be deleted; ``restore`` is skipped when the box
   no longer exists.

   :param box: The container holding the embedded clip.
   :param restore: Rebuilds the placeholder content inside ``box``. Must clear it.
   :param ttl: Idle seconds before reverting. Defaults to
               :attr:`annie.app_state.UiSettings.embed_ttl_seconds`; rendered clips pass
               :func:`render_embed_ttl` so they never outlive the temp-dir sweep.