pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/visual/icons.py

@@ -0,0 +1,117 @@
+"""Headless-safe catalogue for PyCForge's packaged raster iconography."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import MappingProxyType
+from typing import Mapping
+
+
+PYCFORGE_ICON_SIZES = (16, 20, 24, 32, 48, 64, 96, 128, 256)
+
+PYCFORGE_ICON_FILES: Mapping[str, str] = MappingProxyType(
+    {
+        "add-document": "add-document.png",
+        "brand-mark": "brand-mark.png",
+        "cancel": "cancel.png",
+        "check": "check.png",
+        "chevron-right": "chevron-right.png",
+        "close": "close.png",
+        "collapse-all": "collapse-all.png",
+        "command-palette": "command-palette.png",
+        "convert": "convert.png",
+        "copy": "copy.png",
+        "cut": "cut.png",
+        "decision-trace": "decision-trace.png",
+        "details": "details.png",
+        "diagnostics": "diagnostics.png",
+        "duplicate-line": "duplicate-line.png",
+        "exit": "exit.png",
+        "expand-all": "expand-all.png",
+        "find": "find.png",
+        "bundle-search": "bundle-search.png",
+        "go-to-line": "go-to-line.png",
+        "go-to-output": "go-to-output.png",
+        "go-to-source": "go-to-source.png",
+        "history": "history.png",
+        "help": "help.png",
+        "indent": "indent.png",
+        "link-c": "link-c.png",
+        "mappings": "mappings.png",
+        "module": "module.png",
+        "move-down": "move-down.png",
+        "move-line-down": "move-line-down.png",
+        "move-line-up": "move-line-up.png",
+        "move-up": "move-up.png",
+        "next-match": "next.png",
+        "open": "open.png",
+        "outline": "outline.png",
+        "outdent": "outdent.png",
+        "paste": "paste.png",
+        "previous-match": "previous.png",
+        "primary-module": "primary-module.png",
+        "redo": "redo.png",
+        "remove-document": "remove-document.png",
+        "replace": "replace.png",
+        "save-as": "save-as.png",
+        "save-c": "export.png",
+        "save-python": "save.png",
+        "select-all": "select-all.png",
+        "settings": "settings.png",
+        "split-view": "split-view.png",
+        "summary": "summary.png",
+        "telemetry": "telemetry.png",
+        "tools": "tools.png",
+        "toggle-comment": "toggle-comment.png",
+        "toggle-fold": "toggle-fold.png",
+        "undo": "undo.png",
+        "view-c": "show-c.png",
+        "whitespace": "whitespace.png",
+    }
+)
+
+
+def pycforge_icon_root() -> Path:
+    """Return the packaged multi-resolution raster-resource directory."""
+
+    return Path(__file__).parent / "resources" / "icons"
+
+
+def pycforge_brand_icon_path() -> Path:
+    """Return the canonical 24-pixel PyCForge brand mark."""
+
+    return pycforge_icon_path("brand-mark")
+
+
+def pycforge_icon_path(name: str, size: int = 24) -> Path:
+    """Return one exact packaged PNG for a stable logical icon name."""
+
+    try:
+        filename = PYCFORGE_ICON_FILES[name]
+    except KeyError as exc:
+        raise KeyError(f"unknown PyCForge icon: {name}") from exc
+    if isinstance(size, bool) or size not in PYCFORGE_ICON_SIZES:
+        raise ValueError(
+            "icon size must be one of "
+            + ", ".join(str(item) for item in PYCFORGE_ICON_SIZES)
+        )
+    return pycforge_icon_root() / str(size) / filename
+
+
+def pycforge_icon_paths(name: str) -> tuple[tuple[int, Path], ...]:
+    """Return every packaged resolution for one logical icon."""
+
+    return tuple(
+        (size, pycforge_icon_path(name, size))
+        for size in PYCFORGE_ICON_SIZES
+    )
+
+
+__all__ = [
+    "PYCFORGE_ICON_FILES",
+    "PYCFORGE_ICON_SIZES",
+    "pycforge_brand_icon_path",
+    "pycforge_icon_path",
+    "pycforge_icon_paths",
+    "pycforge_icon_root",
+]

pycforge_sdk/gui/visual/qt_actions.py

@@ -0,0 +1,501 @@
+"""Optional Qt materialization of the declared PyCForge action contract."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .action_contract import (
+    ACTION_SPECS,
+    DYNAMIC_ACTION_GROUPS,
+    ActionSpec,
+    ActionState,
+    DynamicActionEntry,
+    validated_dynamic_entries,
+)
+
+
+try:
+    from PySide6.QtCore import QObject, QSignalBlocker, Qt
+    from PySide6.QtGui import QAction, QActionGroup, QIcon, QKeySequence
+    from PySide6.QtWidgets import QToolButton, QWidget
+except (ImportError, ModuleNotFoundError) as exc:
+    QT_ACTIONS_AVAILABLE = False
+    _QT_ERROR = exc
+else:
+    QT_ACTIONS_AVAILABLE = True
+    _QT_ERROR = None
+
+
+ActionHandler = Callable[..., Any]
+ActionStateProvider = Callable[
+    [str | None, object | None],
+    Mapping[str, ActionState],
+]
+
+
+if QT_ACTIONS_AVAILABLE:
+    from .qt_icons import load_pycforge_icon
+
+    _STANDARD_KEYS = {
+        "Open": QKeySequence.StandardKey.Open,
+        "New": QKeySequence.StandardKey.New,
+        "Save": QKeySequence.StandardKey.Save,
+        "SaveAs": QKeySequence.StandardKey.SaveAs,
+        "Undo": QKeySequence.StandardKey.Undo,
+        "Redo": QKeySequence.StandardKey.Redo,
+        "Cut": QKeySequence.StandardKey.Cut,
+        "Copy": QKeySequence.StandardKey.Copy,
+        "Paste": QKeySequence.StandardKey.Paste,
+        "SelectAll": QKeySequence.StandardKey.SelectAll,
+        "Find": QKeySequence.StandardKey.Find,
+        "Replace": QKeySequence.StandardKey.Replace,
+        "FindNext": QKeySequence.StandardKey.FindNext,
+    }
+
+    class QtActionRegistry(QObject):
+        """Own exactly one QAction per declared non-parameterized action."""
+
+        def __init__(
+            self,
+            owner: QWidget,
+            handlers: Mapping[str, ActionHandler] | None = None,
+            *,
+            state_provider: ActionStateProvider | None = None,
+            action_specs: Mapping[str, ActionSpec] = ACTION_SPECS,
+        ) -> None:
+            if owner is None:
+                raise TypeError("owner must be a QWidget")
+            super().__init__(owner)
+            self._owner = owner
+            self._specs = dict(action_specs)
+            self._handlers = dict(handlers or {})
+            self._state_provider = state_provider
+            self._actions: dict[str, QAction] = {}
+            self._exclusive_groups: list[QActionGroup] = []
+            self._dynamic_actions: dict[str, tuple[QAction, ...]] = {}
+            self._last_states: dict[str, ActionState] = {}
+            self._active_surface_id: str | None = None
+            self._active_target: object | None = None
+            for action_id, spec in self._specs.items():
+                if spec.dynamic:
+                    continue
+                action = self._materialize(spec)
+                self._actions[action_id] = action
+                if spec.shortcut_context == "window":
+                    owner.addAction(action)
+            self.refresh()
+
+        @property
+        def active_surface_id(self) -> str | None:
+            return self._active_surface_id
+
+        @property
+        def active_target(self) -> object | None:
+            return self._active_target
+
+        def action(self, action_id: str) -> QAction:
+            """Return the sole QAction for a declared static action."""
+
+            try:
+                return self._actions[action_id]
+            except KeyError as exc:
+                if action_id in self._specs:
+                    raise KeyError(
+                        f"dynamic action has no static instance: {action_id}"
+                    ) from exc
+                raise KeyError(f"unknown PyCForge action: {action_id}") from exc
+
+        def spec(self, action_id: str) -> ActionSpec:
+            try:
+                return self._specs[action_id]
+            except KeyError as exc:
+                raise KeyError(
+                    f"unknown PyCForge action: {action_id}"
+                ) from exc
+
+        def static_action_ids(self) -> tuple[str, ...]:
+            return tuple(self._actions)
+
+        def is_disabled_window_shortcut(
+            self,
+            key: int,
+            modifiers: int,
+        ) -> bool:
+            """Return whether a reserved disabled shortcut must be consumed."""
+
+            modifier_value = getattr(modifiers, "value", modifiers)
+            key_value = getattr(key, "value", key)
+            sequence = QKeySequence(
+                int(modifier_value) | int(key_value)
+            )
+            for action_id, action in self._actions.items():
+                shortcut = action.shortcut()
+                if (
+                    self._specs[action_id].shortcut_context == "window"
+                    and not action.isEnabled()
+                    and not shortcut.isEmpty()
+                    and sequence.matches(shortcut)
+                    == QKeySequence.SequenceMatch.ExactMatch
+                ):
+                    return True
+            return False
+
+        def make_exclusive(self, action_ids: tuple[str, ...]) -> None:
+            """Keep one checked choice across menu and command-palette actions."""
+
+            actions = tuple(self.action(action_id) for action_id in action_ids)
+            if not actions or any(not action.isCheckable() for action in actions):
+                raise ValueError("exclusive choices must be checkable actions")
+            group = QActionGroup(self)
+            group.setExclusive(True)
+            for action in actions:
+                group.addAction(action)
+            self._exclusive_groups.append(group)
+
+        def register_handler(
+            self, action_id: str, handler: ActionHandler
+        ) -> None:
+            if action_id not in self._actions:
+                raise KeyError(f"unknown static action: {action_id}")
+            if not callable(handler):
+                raise TypeError("action handler must be callable")
+            self._handlers[action_id] = handler
+            self.refresh()
+
+        def unregister_handler(self, action_id: str) -> None:
+            self._handlers.pop(action_id, None)
+            self.refresh()
+
+        def set_state_provider(
+            self, provider: ActionStateProvider | None
+        ) -> None:
+            if provider is not None and not callable(provider):
+                raise TypeError("state provider must be callable")
+            self._state_provider = provider
+            self.refresh()
+
+        def set_active_context(
+            self, surface_id: str | None, target: object | None
+        ) -> None:
+            self._active_surface_id = surface_id
+            self._active_target = target
+            self.refresh()
+
+        def clear_active_context(self) -> None:
+            self.set_active_context(None, None)
+
+        def refresh(
+            self,
+            states: Mapping[str, ActionState] | None = None,
+        ) -> None:
+            """Project bounded application state onto every static action."""
+
+            if states is None and self._state_provider is not None:
+                states = self._state_provider(
+                    self._active_surface_id,
+                    self._active_target,
+                )
+            if states is not None:
+                unknown = set(states).difference(self._actions)
+                if unknown:
+                    raise KeyError(
+                        f"state supplied for unknown actions: {sorted(unknown)}"
+                    )
+                if any(
+                    not isinstance(value, ActionState)
+                    for value in states.values()
+                ):
+                    raise TypeError("action states must be ActionState values")
+                self._last_states = dict(states)
+            for action_id, action in self._actions.items():
+                state = self._last_states.get(action_id, ActionState())
+                enabled = state.enabled and action_id in self._handlers
+                # QAction changes are observed by every materialized menu and
+                # toolbar button.  Re-applying an identical value needlessly
+                # invalidates their styles and can visibly flash busy chrome
+                # while the editor publishes rapid, unrelated snapshots.
+                if action.isEnabled() != enabled:
+                    action.setEnabled(enabled)
+                if action.isVisible() != state.visible:
+                    action.setVisible(state.visible)
+                if (
+                    action.isCheckable()
+                    and state.checked is not None
+                    and action.isChecked() != bool(state.checked)
+                ):
+                    blocker = QSignalBlocker(action)
+                    action.setChecked(bool(state.checked))
+                    del blocker
+
+        def set_enabled(self, action_id: str, enabled: bool) -> None:
+            current = self._last_states.get(action_id, ActionState())
+            self._last_states[action_id] = ActionState(
+                enabled=bool(enabled),
+                checked=current.checked,
+                visible=current.visible,
+            )
+            self.refresh(self._last_states)
+
+        def set_checked(self, action_id: str, checked: bool) -> None:
+            action = self.action(action_id)
+            if not action.isCheckable():
+                raise ValueError(f"action is not checkable: {action_id}")
+            current = self._last_states.get(action_id, ActionState())
+            self._last_states[action_id] = ActionState(
+                enabled=current.enabled,
+                checked=bool(checked),
+                visible=current.visible,
+            )
+            self.refresh(self._last_states)
+
+        def attach_to_widget(
+            self, action_id: str, widget: QWidget
+        ) -> QAction:
+            """Attach a widget-scoped shortcut to its intended owner."""
+
+            action = self.action(action_id)
+            if self.spec(action_id).shortcut_context != "widget":
+                raise ValueError(
+                    f"action is not widget-scoped: {action_id}"
+                )
+            widget.addAction(action)
+            return action
+
+        def bind_tool_button(
+            self,
+            action_id: str,
+            button: QToolButton,
+            *,
+            accessible_description: str | None = None,
+        ) -> None:
+            """Bind a button without duplicating labels, icons, or callbacks."""
+
+            if not isinstance(button, QToolButton):
+                raise TypeError("button must be a QToolButton")
+            spec = self.spec(action_id)
+            button.setDefaultAction(self.action(action_id))
+            button.setAccessibleName(spec.accessible_name)
+            if accessible_description:
+                button.setAccessibleDescription(accessible_description)
+
+        def replace_dynamic(
+            self,
+            group_id: str,
+            entries: tuple[DynamicActionEntry, ...] | list[DynamicActionEntry],
+            handler: Callable[[str], Any],
+        ) -> tuple[QAction, ...]:
+            """Replace a bounded parameterized group owned by this registry."""
+
+            if group_id not in DYNAMIC_ACTION_GROUPS:
+                raise KeyError(f"unknown dynamic action group: {group_id}")
+            if not callable(handler):
+                raise TypeError("dynamic action handler must be callable")
+            records = validated_dynamic_entries(entries)
+            if not records:
+                records = (
+                    DynamicActionEntry(
+                        key="empty",
+                        label="No recent Python documents",
+                        tooltip="No recent Python documents are available",
+                        accessible_name="No recent Python documents",
+                        payload="",
+                        enabled=False,
+                    ),
+                )
+            for action in self._dynamic_actions.get(group_id, ()):
+                action.setParent(None)
+                action.deleteLater()
+            template = self.spec(DYNAMIC_ACTION_GROUPS[group_id])
+            actions = tuple(
+                self._materialize_dynamic(
+                    group_id, template, entry, handler, index
+                )
+                for index, entry in enumerate(records)
+            )
+            self._dynamic_actions[group_id] = actions
+            return actions
+
+        def dynamic_actions(self, group_id: str) -> tuple[QAction, ...]:
+            if group_id not in DYNAMIC_ACTION_GROUPS:
+                raise KeyError(f"unknown dynamic action group: {group_id}")
+            return self._dynamic_actions.get(group_id, ())
+
+        def _materialize(self, spec: ActionSpec) -> QAction:
+            icon = (
+                load_pycforge_icon(spec.icon_name)
+                if spec.icon_name else QIcon()
+            )
+            action = QAction(icon, spec.menu_text, self._owner)
+            action.setObjectName(
+                "pycforgeAction__" + spec.action_id.replace(".", "__")
+            )
+            action.setData(spec.action_id)
+            action.setIconText(spec.toolbar_text)
+            action.setCheckable(spec.checkable)
+            action.setAutoRepeat(False)
+            action.setProperty("pycforgeActionId", spec.action_id)
+            action.setProperty("pycforgeTone", spec.tone)
+            action.setProperty(
+                "pycforgeAccessibleName", spec.accessible_name
+            )
+            sequence = self._shortcut(spec)
+            if sequence is not None:
+                action.setShortcut(sequence)
+                context = (
+                    Qt.ShortcutContext.WidgetWithChildrenShortcut
+                    if spec.shortcut_context == "widget"
+                    else Qt.ShortcutContext.WindowShortcut
+                )
+                action.setShortcutContext(context)
+            tooltip = self._tooltip(spec.tooltip, sequence)
+            action.setToolTip(tooltip)
+            action.setWhatsThis(spec.tooltip)
+            action.triggered.connect(
+                lambda checked=False, action_id=spec.action_id:
+                self._invoke(action_id, checked)
+            )
+            return action
+
+        def _materialize_dynamic(
+            self,
+            group_id: str,
+            template: ActionSpec,
+            entry: DynamicActionEntry,
+            handler: Callable[[str], Any],
+            index: int,
+        ) -> QAction:
+            icon = (
+                load_pycforge_icon(template.icon_name)
+                if template.icon_name else QIcon()
+            )
+            action = QAction(
+                icon, entry.label.replace("&", "&&"), self._owner
+            )
+            action.setObjectName(
+                f"pycforgeDynamic__{group_id}__{index}"
+            )
+            action.setData((group_id, entry.key))
+            action.setEnabled(entry.enabled)
+            action.setToolTip(entry.tooltip)
+            action.setProperty("pycforgeActionId", template.action_id)
+            action.setProperty("pycforgeTone", template.tone)
+            action.setProperty(
+                "pycforgeAccessibleName", entry.accessible_name
+            )
+            if entry.enabled:
+                action.triggered.connect(
+                    lambda checked=False, payload=entry.payload:
+                    handler(payload)
+                )
+            return action
+
+        def _invoke(self, action_id: str, checked: bool) -> None:
+            handler = self._handlers.get(action_id)
+            if handler is None:
+                return
+            if self._specs[action_id].checkable:
+                handler(bool(checked))
+            else:
+                handler()
+
+        @staticmethod
+        def _shortcut(spec: ActionSpec) -> QKeySequence | None:
+            if spec.standard_shortcut:
+                try:
+                    return QKeySequence(
+                        _STANDARD_KEYS[spec.standard_shortcut]
+                    )
+                except KeyError as exc:
+                    raise ValueError(
+                        "unknown standard shortcut: "
+                        f"{spec.standard_shortcut}"
+                    ) from exc
+            if spec.shortcut:
+                return QKeySequence(spec.shortcut)
+            return None
+
+        @staticmethod
+        def _tooltip(
+            tooltip: str, sequence: QKeySequence | None
+        ) -> str:
+            if sequence is None or sequence.isEmpty():
+                return tooltip
+            rendered = sequence.toString(
+                QKeySequence.SequenceFormat.NativeText
+            )
+            return f"{tooltip} ({rendered})" if rendered else tooltip
+
+
+    def build_window_system_actions(
+        owner: QWidget,
+        handlers: Mapping[str, ActionHandler],
+    ) -> dict[str, QAction]:
+        """Create the bounded frameless-window commands at the action seam.
+
+        These four platform-window commands are not workspace actions and do
+        not expand the frozen declarative action contract.  Their QAction
+        construction still remains singly owned by this module.
+        """
+
+        if owner is None:
+            raise TypeError("owner must be a QWidget")
+        specifications = (
+            ("restore", "&Restore", "Restore window", None),
+            ("minimize", "Mi&nimize", "Minimize window", None),
+            ("maximize", "Ma&ximize", "Maximize window", None),
+            ("close", "&Close", "Close window", "Alt+F4"),
+        )
+        required = {key for key, *_remainder in specifications}
+        if set(handlers) != required or any(
+            not callable(handlers[key]) for key in required
+        ):
+            raise ValueError(
+                "window system handlers must be exactly restore, minimize, "
+                "maximize, and close"
+            )
+
+        actions: dict[str, QAction] = {}
+        for key, label, description, shortcut in specifications:
+            action = QAction(label, owner)
+            action.setObjectName(f"pycforgeWindowAction__{key}")
+            action.setData(("window-system", key))
+            action.setAutoRepeat(False)
+            action.setProperty("pycforgeWindowCommand", key)
+            action.setProperty("pycforgeAccessibleName", description)
+            action.setToolTip(description)
+            if shortcut is not None:
+                action.setShortcut(QKeySequence(shortcut))
+                action.setShortcutContext(
+                    Qt.ShortcutContext.WindowShortcut
+                )
+            action.triggered.connect(
+                lambda _checked=False, callback=handlers[key]: callback()
+            )
+            actions[key] = action
+        return actions
+
+
+else:
+    class QtActionRegistry:
+        """Import-safe placeholder for a damaged installation without PySide6."""
+
+        def __init__(self, *_args, **_kwargs) -> None:
+            raise RuntimeError(
+                "PySide6 is required for the PyCForge action registry"
+            ) from _QT_ERROR
+
+
+    def build_window_system_actions(*_args, **_kwargs):
+        raise RuntimeError(
+            "PySide6 is required for PyCForge window actions"
+        ) from _QT_ERROR
+
+
+__all__ = [
+    "ActionHandler",
+    "ActionStateProvider",
+    "QT_ACTIONS_AVAILABLE",
+    "QtActionRegistry",
+    "build_window_system_actions",
+]

pycforge_sdk/gui/visual/qt_branding.py

@@ -0,0 +1,47 @@
+"""Accessible PyCForge lettering with a consistent steel-blue C."""
+from html import escape
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QLabel
+
+from .qt_workspace_widgets import ElidedLabel
+from .visual_tokens import PYCFORGE_COLORS
+
+
+def brand_html(text: str) -> str:
+    """Escape arbitrary titles before adding the single brand accent."""
+    return escape(text).replace(
+        'PyCForge', f'Py<span style="color:{PYCFORGE_COLORS.blue}">C</span>Forge'
+    )
+
+
+class BrandLabel(QLabel):
+    """Keep plain semantic text available while painting the brand accent."""
+    def __init__(self, text='', parent=None):
+        super().__init__(parent)
+        self.setTextFormat(Qt.TextFormat.RichText)
+        self.setText(text)
+
+    def setText(self, text):
+        self._plain_text = str(text)
+        super().setText(brand_html(self._plain_text))
+        self.setAccessibleName(self._plain_text)
+
+    def text(self):
+        return self._plain_text
+
+
+class BrandElidedLabel(ElidedLabel):
+    """Elide plain title text first; markup never affects width or identity."""
+    _displayed_plain = ""
+
+    @property
+    def displayed_text(self):
+        return self._displayed_plain
+
+    def _refresh_elision(self):
+        self._displayed_plain = self.fontMetrics().elidedText(
+            self._full_text, self._elide_mode, max(0, self.contentsRect().width() - 2)
+        )
+        self.setTextFormat(Qt.TextFormat.RichText)
+        QLabel.setText(self, brand_html(self._displayed_plain))