"""Deferred dock panel registration helper.

Replaces the manual ``QTimer.singleShot()`` + duplicate-check +
try/except pattern used in ``src/Mod/Create/InitGui.py``.
"""

import FreeCAD

_AREA_MAP = {
    "left": 1,  # Qt.LeftDockWidgetArea
    "right": 2,  # Qt.RightDockWidgetArea
    "top": 4,  # Qt.TopDockWidgetArea
    "bottom": 8,  # Qt.BottomDockWidgetArea
}


def register_dock_panel(object_name, title, widget_factory, area="right", delay_ms=0):
    """Register a dock panel, optionally deferred.

    Parameters
    ----------
    object_name : str
        Qt object name for duplicate prevention.
    title : str
        Dock widget title bar text.
    widget_factory : callable
        Zero-argument callable returning a ``QWidget``.  Called only
        when the panel is actually created (after *delay_ms*).
    area : str, optional
        Dock area: ``"left"``, ``"right"``, ``"top"``, or ``"bottom"``.
        Default ``"right"``.
    delay_ms : int, optional
        Milliseconds to wait before creating the panel.  Default 0
        (immediate, but still posted to the event loop).
    """
    if not isinstance(object_name, str):
        raise TypeError(f"object_name must be str, got {type(object_name).__name__}")
    if not callable(widget_factory):
        raise TypeError("widget_factory must be callable")

    qt_area = _AREA_MAP.get(area)
    if qt_area is None:
        raise ValueError(f"area must be one of {list(_AREA_MAP)}, got {area!r}")

    def _create():
        try:
            from PySide import QtCore, QtWidgets

            import FreeCADGui

            mw = FreeCADGui.getMainWindow()
            if mw is None:
                return

            if mw.findChild(QtWidgets.QDockWidget, object_name):
                return

            widget = widget_factory()
            panel = QtWidgets.QDockWidget(title, mw)
            panel.setObjectName(object_name)
            panel.setWidget(widget)
            mw.addDockWidget(QtCore.Qt.DockWidgetArea(qt_area), panel)
        except Exception as e:
            FreeCAD.Console.PrintLog(f"kindred_sdk: Dock panel '{object_name}' skipped: {e}\n")

    try:
        from PySide.QtCore import QTimer

        QTimer.singleShot(max(0, delay_ms), _create)
    except Exception as e:
        FreeCAD.Console.PrintLog(
            f"kindred_sdk: Could not schedule dock panel '{object_name}': {e}\n"
        )