ui_event_logger.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/ui_event_logger.py
 
"""
UI Event Logger
===============
 
Purpose
-------
Register a single Dash callback that captures all user interactions across
an instrumented Dash application and routes every genuine event through
``_dbg()``.
 
Responsibilities
----------------
- Register a universal ``ALL``-pattern ``Input`` callback that listens to
  ``n_clicks``, ``value``, ``data``, ``figure``, and ``selectedData`` on
  all instrumented components (those whose IDs were rewritten to
  ``{"event": "<original-id>"}``).
- Use ``ctx.triggered_prop_ids`` to build the set of ``(original_id,
  prop_name)`` pairs that actually triggered the current cycle, filtering
  out components that are non-``None`` but did not change (e.g. a Dropdown
  holding its default selection).
- Log each genuine user interaction via
  ``_dbg("UI", ..., override=True)`` so UI events always appear in the log
  regardless of domain debug levels.
- Truncate large event values before logging (``_MAX_EVENT_VALUE_LEN``).
  For ``figure`` and ``data`` properties, log type + length summary unless
  ``DEBUG_LEVELS["UI"] >= 9``.
- Emit a clear L1 diagnostic warning when the required
  ``dcc.Store(id=REQUIRED_STORE_ID)`` component is absent from
  ``app.layout`` at registration time.
 
Diagnostics
-----------
Domain: UI
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must only log events that actually triggered the current callback cycle.
- Must route all log output through ``_dbg()`` with ``override=True``.
- Requires Dash (``pip install oc_diagnostics[dash]``).
- Must return ``no_update`` from the callback so the store is not dirtied.
- Must not raise; logging failures must be silently swallowed.
- Event values must be truncated to ``_MAX_EVENT_VALUE_LEN`` characters in
  ``repr()`` form before being passed to ``_dbg()``.
- A L1 warning must be emitted when ``REQUIRED_STORE_ID`` is not found in
  ``app.layout`` at ``register_callbacks()`` time.
"""
 
from dash import Input, Output, State, ALL, ctx, no_update
from oc_diagnostics.unified_debug import _dbg, DEBUG_LEVELS, UI_EVENT_PROPERTIES
 
 
# ============================================================
# PUBLIC CONSTANT — required dcc.Store ID
# ============================================================
 
REQUIRED_STORE_ID = "debug-settings-data-store"
"""The ``id`` of the ``dcc.Store`` component that the UI event logger callback
writes to.  This store must be present in the Dash layout before
``register_callbacks()`` is called; if it is absent Dash will raise a generic
callback registration error at startup."""
 
 
# ============================================================
# PRIVATE CONSTANTS
# ============================================================
 
_MAX_EVENT_VALUE_LEN = 500
"""Maximum length (in characters) of the ``repr()`` of a logged event value.
 
Values whose repr exceeds this limit are truncated and annotated with the
original length.  ``figure`` and ``data`` properties are summarised as
``<type len=N>`` unless ``DEBUG_LEVELS["UI"] >= 9``.
"""
 
# Properties whose payloads can be very large; summarised at low debug levels.
_STRUCTURED_PROPS = frozenset({"figure", "data"})
 
 
# ============================================================
# INTERNAL HELPERS
# ============================================================
 
def _format_event_value(prop_name: str, value) -> str:
    """Return a log-safe string representation of *value*.
 
    For structured properties (``figure``, ``data``) the full repr is only
    returned when ``DEBUG_LEVELS["UI"] >= 9``; otherwise a concise type +
    length summary is returned.  For all other properties the repr is
    truncated at ``_MAX_EVENT_VALUE_LEN`` characters.
    """
    if prop_name in _STRUCTURED_PROPS:
        if DEBUG_LEVELS.get("UI", 0) < 9:
            length = len(value) if isinstance(value, (dict, list)) else "?"
            return f"<{type(value).__name__} len={length}> (set UI level=9 for full value)"
 
    raw = repr(value)
    if len(raw) > _MAX_EVENT_VALUE_LEN:
        return raw[:_MAX_EVENT_VALUE_LEN] + f"... [{len(raw)} chars total]"
    return raw
 
 
def _find_component_id(node, target_id: str, _depth: int = 0) -> bool:
    """Recursively search *node* (a Dash layout) for a component with *target_id*.
 
    Returns ``True`` as soon as a match is found; stops at depth 100 to
    avoid performance issues on very large layouts.
    """
    if _depth > 100 or node is None:
        return False
    if callable(node):
        # Callable layout — cannot inspect before first request; skip check.
        return False
    if getattr(node, "id", None) == target_id:
        return True
    children = getattr(node, "children", None)
    if isinstance(children, (list, tuple)):
        return any(_find_component_id(ch, target_id, _depth + 1) for ch in children)
    if children is not None:
        return _find_component_id(children, target_id, _depth + 1)
    return False
 
 
def _check_store_present(app) -> None:
    """Emit a L1 warning if ``REQUIRED_STORE_ID`` is absent from ``app.layout``.
 
    Silently skips the check when:
    - ``app.layout`` is ``None`` (layout not yet assigned), or
    - ``app.layout`` is a callable (resolved at request time).
    """
    try:
        layout = getattr(app, "layout", None)
        if layout is None:
            _dbg(
                "UI",
                "register_callbacks",
                f"WARNING: app.layout is None — cannot verify "
                f"'{REQUIRED_STORE_ID}' is present.  "
                f"Add dcc.Store(id='{REQUIRED_STORE_ID}') before calling "
                f"register_callbacks().",
                level=1,
                override=True,
            )
            return
        if callable(layout):
            return  # Callable layout resolved at request time; skip check.
        if not _find_component_id(layout, REQUIRED_STORE_ID):
            _dbg(
                "UI",
                "register_callbacks",
                f"WARNING: '{REQUIRED_STORE_ID}' not found in app.layout — "
                f"the UI event logger callback will fail at runtime.  "
                f"Add dcc.Store(id='{REQUIRED_STORE_ID}', storage_type='memory') "
                f"to the layout before calling register_callbacks().",
                level=1,
                override=True,
            )
    except Exception:
        pass
 
 
# ============================================================
# REGISTER CALLBACKS
# ============================================================
 
def register_callbacks(app):
    """
    Register the universal UI event logger callback.
 
    This callback listens to the following properties on ALL components
    whose IDs were instrumented into {"event": "<original-id>"}:
 
        - n_clicks
        - value
        - data
        - figure
        - selectedData
 
    These cover all interactive Dash components:
        Buttons, Dropdowns, Inputs, Checklists, Sliders, Stores,
        Graphs, Tabs, etc.
 
    Dash requires explicit property names (no ALL wildcard allowed),
    so we register one Input() per property.
 
    Prerequisites
    -------------
    The layout must contain ``dcc.Store(id=REQUIRED_STORE_ID, ...)``.  A L1
    warning is emitted at registration time when this component is not found.
 
    Note
    ----
    The ``ui_event_properties`` setting is read once at callback registration
    time.  Changes to ``global_settings.ui_event_properties`` (via config
    hot-reload or ``set_global_setting()``) will NOT be picked up by an
    already-registered callback — a full application restart is required.
    """
 
    _check_store_present(app)
    _dbg("UI", "register_callbacks", "UI event logger registered", override=True)
 
    @app.callback(
        Output(REQUIRED_STORE_ID, "data", allow_duplicate=True),
        # FS-10: property list is configurable via global_settings.ui_event_properties
        [Input({"event": ALL}, prop) for prop in UI_EVENT_PROPERTIES],
        State({"event": ALL}, "id"),
        prevent_initial_call=True,
    )
    def _log_ui_events(*args):
        # OI-28: *args accepts any number of Input() lists so this callback
        # works correctly regardless of the UI_EVENT_PROPERTIES length.
        # Positional layout: one list per UI_EVENT_PROPERTIES entry (in
        # registration order), followed by the event_ids list from State().
        n_props = len(UI_EVENT_PROPERTIES)
        prop_lists = args[:n_props]
        event_ids = args[n_props] if len(args) > n_props else []
 
        func = "_log_ui_events"
 
        if not event_ids:
            _dbg("UI", func, "No event_ids received", override=True)
            return no_update
 
        # Build a set of (original_event_id, prop_name) pairs that actually
        # triggered this callback cycle.  ctx.triggered_prop_ids maps each
        # Dash prop_id string (e.g. '{"event":"btn"}.n_clicks') to its id
        # dict.  We parse the property name from the trailing ".prop" segment
        # and the original component id from the id dict so we can filter the
        # inner loop to real user-driven changes only.
        triggered_set: set[tuple[str, str]] = set()
        for prop_id_str, id_dict in (ctx.triggered_prop_ids or {}).items():
            if "." in prop_id_str and isinstance(id_dict, dict) and "event" in id_dict:
                prop_part = prop_id_str.rsplit(".", 1)[1]
                triggered_set.add((id_dict["event"], prop_part))
 
        # Iterate dynamically over whatever properties were registered.
        for prop_name, values in zip(UI_EVENT_PROPERTIES, prop_lists):
            for value, eid in zip(values, event_ids):
 
                # Skip noise (None means "no change")
                if value is None:
                    continue
 
                original_id = eid.get("event")
 
                # Skip components whose value is non-None but did not change
                # this cycle (e.g. a Dropdown holding its default selection).
                if (original_id, prop_name) not in triggered_set:
                    continue
 
                formatted = _format_event_value(prop_name, value)
                _dbg(
                    "UI",
                    func,
                    f"EVENT: id={original_id}, property={prop_name}, value={formatted}",
                    override=True,
                )
 
        return no_update
 
 
# Backwards-compatible alias used in your self-test app
def ui_event_logger(app):
    """Convenience wrapper to match existing usage."""
    register_callbacks(app)