karcytics-sdk 2.3.0__tar.gz → 2.4.0__tar.gz

{karcytics_sdk-2.3.0/src/karcytics_sdk.egg-info → karcytics_sdk-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karcytics-sdk
-Version: 2.3.0
+Version: 2.4.0
 Summary: Software Development Kit and CLI for Karcytics.
 Author: Kalaimaran Balasothy
 License: # PolyForm Noncommercial License 1.0.0

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "karcytics-sdk"
-version = "2.3.0"
+version = "2.4.0"
 description = "Software Development Kit and CLI for Karcytics."
 readme = "README.md"
 license = { file = "LICENSE" }

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/academy_driver.py

@@ -24,6 +24,7 @@ from PyQt6.QtCore import QObject, QRect, QTimer
 from PyQt6.QtWidgets import QApplication, QScrollArea, QWidget
 
 from .academy import AcademyManager
+from .tutorial_highlight import TutorialHighlight
 from .tutorial_models import (
     ActionStep,
     BranchingStep,
@@ -86,6 +87,10 @@ class AcademyStepDriver(QObject):
         self._failure_hint_shown = False
         self._was_reviewing = False
         self._last_canvas_guide_active = False
+        # In-window spotlights for targets in other windows (see _spotlight_rects).
+        self._window_highlights: dict[QWidget, TutorialHighlight] = {}
+        # Step whose targets were last scrolled into view (see _update_targets).
+        self._revealed_step_id: str | None = None
 
         self._timer = QTimer(self)
         self._timer.timeout.connect(self._tick)
@@ -468,11 +473,16 @@ class AcademyStepDriver(QObject):
                 if w and w.isVisible():
                     targets.append(w)
 
-        rects = []
-        for w in targets:
-            global_pos = w.mapToGlobal(w.rect().topLeft())
-            local_pos = self._overlay.mapFromGlobal(global_pos)
-            rects.append(QRect(local_pos, w.size()))
+        # A step's first tick with targets: scroll them into view. Otherwise one
+        # scrolled out of a sidebar is spotlit off-screen, Cyto and the bubble
+        # follow it there, and the learner sees only the dim. Once per step,
+        # so they can still scroll away afterwards. (Not before the targets
+        # exist: a popup the step points into may open a few ticks later.)
+        if targets and getattr(step, "id", None) != self._revealed_step_id:
+            self._revealed_step_id = getattr(step, "id", None)
+            _scroll_into_view(targets)
+
+        rects = self._spotlight_rects(targets)
         rects.extend(self._collect_canvas_target_rects(step))
         self._overlay.set_targets(rects)
 
@@ -488,6 +498,47 @@ class AcademyStepDriver(QObject):
                 scroll_target = scroll_area.viewport()
         self._overlay.set_scroll_target(scroll_target)
 
+    def _spotlight_rects(self, targets: list[QWidget]) -> list[QRect]:
+        """Overlay rects for `targets`; targets in other windows are framed there.
+
+        A target in the overlay's own window gets a spotlight hole as usual.
+        One inside another window — a dialog or popup, even one parented to
+        the panel (so `findChildren()` finds it) — would otherwise be
+        spotlit on the main window *underneath* that window. Those are framed
+        inside their own window by a `TutorialHighlight` instead, and that
+        window's frame becomes the overlay rect, so Cyto and the bubble steer
+        clear of the whole window rather than sitting behind it.
+        """
+        from PyQt6 import sip
+
+        # Forget windows that have since been destroyed (a closed dialog).
+        self._window_highlights = {w: h for w, h in self._window_highlights.items() if not sip.isdeleted(w)}
+        own_window = self._overlay.window()
+        rects: list[QRect] = []
+        elsewhere: dict[QWidget, list[QWidget]] = {}
+        for w in targets:
+            window = w.window()
+            if window is None or window is own_window:
+                local_pos = self._overlay.mapFromGlobal(w.mapToGlobal(w.rect().topLeft()))
+                rects.append(QRect(local_pos, w.size()))
+            else:
+                inner = elsewhere.setdefault(window, [])
+                if w is not window and w not in inner:
+                    inner.append(w)
+
+        for window, widgets in elsewhere.items():
+            highlight = self._window_highlights.get(window)
+            if highlight is None:
+                highlight = TutorialHighlight(window)
+                self._window_highlights[window] = highlight
+            highlight.show_on(widgets)
+            frame = window.frameGeometry()
+            rects.append(QRect(self._overlay.mapFromGlobal(frame.topLeft()), frame.size()))
+        for window, highlight in self._window_highlights.items():
+            if window not in elsewhere:
+                highlight.clear()
+        return rects
+
     def _find_in_other_windows(self, name: str) -> list[QWidget]:
         """Visible widgets named `name` in this process's *other* top-level
         windows — e.g. the SDK Preferences dialog, a separate window parented
@@ -549,6 +600,16 @@ class AcademyStepDriver(QObject):
         return None
 
 
+def _scroll_into_view(widgets: list[QWidget]) -> None:
+    """Scrolls each widget's nearest `QScrollArea` so it shows — last
+    first, so when they don't all fit, the first-named one wins.
+    """
+    for w in reversed(widgets):
+        area = AcademyStepDriver._find_scroll_area_ancestor(w)
+        if area is not None:
+            area.ensureWidgetVisible(w, 0, 0)
+
+
 # ── Generic Academy launch — shared by any isolated plugin's own UI trigger ──
 #
 # Originally private to `ui_daemon_runtime.py`'s Help-menu wiring. Promoted

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/question_panel.py

@@ -47,6 +47,16 @@ _REVEAL_NOTE = "The outlined answer is correct — select it to continue."
 _MULTI_MISSING = "Not quite — at least one correct answer is still unselected."
 
 
+def _claim_wrapped_height(label: QLabel, width: int) -> None:
+    """Makes a word-wrapped label ask for all its lines at `width`.
+
+    A wrapped QLabel's sizeHint() assumes its own preferred width, not the
+    fixed one it's given here, and the bubble is sized from sizeHint() — so
+    the last line or two (a long explanation) would be clipped.
+    """
+    label.setMinimumHeight(label.heightForWidth(width))
+
+
 class _ChoiceRow(QFrame):
     """One answer: an indicator plus a word-wrapped label; the whole row clicks."""
 
@@ -65,6 +75,7 @@ class _ChoiceRow(QFrame):
         row.addWidget(self.label, 1)
         self.setFixedWidth(width)
         theme_manager.apply_style(self, _ROW_QSS)
+        _claim_wrapped_height(self.label, width - 20 - 8 - indicator.sizeHint().width())
 
     def mousePressEvent(self, event) -> None:  # noqa: N802
         if self.indicator.isEnabled():
@@ -205,6 +216,7 @@ class QuestionPanel(QWidget):
 
     def _show_feedback(self, text: str, state: str) -> None:
         self.feedback.setText(text)
+        _claim_wrapped_height(self.feedback, self.feedback.width())
         self.feedback.setProperty("state", state)
         style = self.feedback.style()
         if style is not None:

karcytics_sdk-2.4.0/src/karcytics_sdk/plugin/tutorial_highlight.py

@@ -0,0 +1,84 @@
+"""Academy spotlight drawn inside a window other than the overlay's own.
+
+The `TutorialOverlay` is a child of the plugin's main window and can't paint
+over a separate window. A step's target inside a dialog or popup (a Tool
+window, a non-modal QDialog…) would otherwise be spotlit on the main window
+*underneath* it — wherever the target happens to sit on screen. The
+`AcademyStepDriver` instead gives each such window one of these, which draws
+accent frames over the targets inside that window itself.
+"""
+
+from __future__ import annotations
+
+from PyQt6.QtCore import QPoint, QRect, Qt, QTimer
+from PyQt6.QtWidgets import QFrame, QWidget
+
+from .theme_fallback import theme_manager
+
+# The driver refreshes every tick (100 ms); once it stops (step changed,
+# window closed, Academy hidden) the frames disappear on their own.
+_EXPIRE_MS = 400
+_PAD = 3
+
+
+def _visible_rect(widget: QWidget) -> QRect:
+    """`widget`'s own rect clipped by every ancestor (e.g. a scroll viewport)."""
+    rect = widget.rect()
+    child, parent = widget, widget.parentWidget()
+    while parent is not None and not child.isWindow():
+        offset = widget.mapTo(parent, QPoint(0, 0))
+        rect = rect.intersected(parent.rect().translated(-offset))
+        child, parent = parent, parent.parentWidget()
+    return rect
+
+
+class TutorialHighlight:
+    """Accent frames over widgets inside `host` (a top-level window)."""
+
+    def __init__(self, host: QWidget) -> None:
+        self.host = host
+        self._frames: list[QFrame] = []
+        self._expiry = QTimer(host)
+        self._expiry.setSingleShot(True)
+        self._expiry.timeout.connect(self.clear)
+
+    @property
+    def visible_count(self) -> int:
+        return sum(1 for f in self._frames if f.isVisible())
+
+    def show_on(self, widgets: list[QWidget]) -> None:
+        """Frames exactly `widgets` (descendants of `host`); hides the rest.
+
+        Only the part of each widget that's actually on screen is framed —
+        one scrolled out of its scroll area gets no frame, rather than one
+        drawn over whatever sits where it would be (a dialog's buttons).
+        """
+        shown = [(w, r) for w in widgets if not (r := _visible_rect(w)).isEmpty()]
+        while len(self._frames) < len(shown):
+            self._frames.append(self._new_frame())
+        for frame, (widget, rect) in zip(self._frames, shown, strict=False):
+            top_left = widget.mapTo(self.host, rect.topLeft())
+            frame.setGeometry(QRect(top_left, rect.size()).adjusted(-_PAD, -_PAD, _PAD, _PAD))
+            frame.show()
+            frame.raise_()
+        for frame in self._frames[len(shown) :]:
+            frame.hide()
+        self._expiry.start(_EXPIRE_MS)
+
+    def clear(self) -> None:
+        for frame in self._frames:
+            frame.hide()
+
+    def _new_frame(self) -> QFrame:
+        frame = QFrame(self.host)
+        frame.setObjectName("TutorialHighlightFrame")
+        frame.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        theme_manager.apply_style(
+            frame,
+            "QFrame#TutorialHighlightFrame {"
+            "  border: 2px solid {ACCENT_PRIMARY};"
+            "  border-radius: 6px;"
+            "  background: transparent;"
+            "}",
+        )
+        return frame

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk/plugin/tutorial_overlay.py

@@ -1271,7 +1271,16 @@ class TutorialOverlay(QWidget):
         panel.content_changed.connect(self._on_question_content_changed)
 
     def _on_question_content_changed(self) -> None:
-        """Feedback appeared or grew: re-fit the bubble and re-punch the mask."""
+        """Feedback appeared or grew: re-fit the bubble and re-punch the mask.
+
+        Once now and once on the next event-loop turn: the panel's own layout
+        only settles after its pending LayoutRequest, and fitting to the stale
+        size hint squeezes the choices and clips the explanation's last lines.
+        """
+        self._refit_for_question()
+        QTimer.singleShot(0, self._refit_for_question)
+
+    def _refit_for_question(self) -> None:
         if not self._is_alive():
             return
         self._force_resize()
@@ -1442,6 +1451,9 @@ class TutorialOverlay(QWidget):
         while self.dynamic_content.count():
             item = self.dynamic_content.takeAt(0)
             if item.widget():
+                # Hidden now; deleteLater() waits for the event loop to come
+                # back round, and until then it would still paint in the bubble.
+                item.widget().hide()
                 item.widget().deleteLater()
 
     def _force_resize(self) -> None:

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0/src/karcytics_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karcytics-sdk
-Version: 2.3.0
+Version: 2.4.0
 Summary: Software Development Kit and CLI for Karcytics.
 Author: Kalaimaran Balasothy
 License: # PolyForm Noncommercial License 1.0.0

{karcytics_sdk-2.3.0 → karcytics_sdk-2.4.0}/src/karcytics_sdk.egg-info/SOURCES.txt

@@ -72,6 +72,7 @@ src/karcytics_sdk/plugin/signals.py
 src/karcytics_sdk/plugin/state.py
 src/karcytics_sdk/plugin/theme_fallback.py
 src/karcytics_sdk/plugin/toast.py
+src/karcytics_sdk/plugin/tutorial_highlight.py
 src/karcytics_sdk/plugin/tutorial_models.py
 src/karcytics_sdk/plugin/tutorial_overlay.py
 src/karcytics_sdk/plugin/ui_daemon_runtime.py