pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/visual/theme_workspace_stylesheet.py

@@ -0,0 +1,169 @@
+"""Phase 15C editor-workspace additions to the PyCForge visual system."""
+
+from __future__ import annotations
+
+from string import Template
+
+from .visual_tokens import (
+    PYCFORGE_COLORS,
+    PyCForgeColors,
+    color_tokens,
+)
+
+
+_WORKSPACE_QSS = Template(
+    r"""
+QTabBar#SourceDocumentTabs {
+    background: ${canvas};
+    border: 1px solid ${border};
+    border-bottom: 1px solid ${border_strong};
+    border-radius: 5px;
+    padding: 3px 4px 0 4px;
+}
+QTabBar#SourceDocumentTabs::tab {
+    color: ${text_soft};
+    background: ${surface};
+    border: 1px solid ${border};
+    border-bottom: 2px solid ${border};
+    border-top-left-radius: 4px;
+    border-top-right-radius: 4px;
+    padding: 7px 12px;
+    min-width: 110px;
+}
+QTabBar#SourceDocumentTabs::tab:hover {
+    color: ${text};
+    background: ${surface_hover};
+    border-bottom: 2px solid ${blue};
+}
+QTabBar#SourceDocumentTabs::tab:selected {
+    color: ${text};
+    background: ${selection};
+    border-color: ${blue};
+    border-bottom: 2px solid ${violet_bright};
+}
+QTabBar#SourceDocumentTabs:focus {
+    border: 1px solid ${focus_ring};
+    border-bottom: 2px solid ${violet};
+}
+QWidget#SourceBreadcrumbBar {
+    background: ${surface};
+    border: 1px solid ${border};
+    border-left: 2px solid ${blue};
+    border-radius: 4px;
+}
+QToolButton#BreadcrumbButton {
+    color: ${text_soft};
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: 4px;
+    padding: 3px 7px;
+}
+QToolButton#BreadcrumbButton:hover {
+    color: ${text};
+    background: ${surface_hover};
+    border-color: ${blue_dim};
+}
+QToolButton#BreadcrumbButton:focus {
+    color: ${text};
+    border: 1px solid ${focus_ring};
+    background: ${selection};
+}
+QLabel#BreadcrumbSeparator {
+    color: ${violet_bright};
+    padding: 0 1px;
+}
+QDialog#CommandPaletteDialog {
+    background: ${canvas};
+}
+QDialog#EditorTextSizeDialog {
+    background: ${canvas};
+}
+QLabel#EditorSettingsDescription {
+    color: ${text_soft};
+    padding: 3px 2px 7px 2px;
+}
+QSpinBox#EditorFontPointSize {
+    color: ${text};
+    background: ${void};
+    border: 1px solid ${blue};
+    border-bottom: 2px solid ${violet};
+    padding: 6px 8px;
+}
+QPlainTextEdit#EditorFontPreview {
+    color: ${text};
+    background: ${void};
+    border: 1px solid ${border_strong};
+    border-left: 3px solid ${warm};
+    border-radius: 4px;
+    padding: 8px;
+}
+QLineEdit#CommandPaletteQuery {
+    color: ${text};
+    background: ${void};
+    border: 1px solid ${blue};
+    border-bottom: 2px solid ${violet};
+    border-radius: 4px;
+    padding: 9px 11px;
+}
+QTreeWidget#CommandPaletteResults,
+QTreeWidget#BundleSearchTree,
+QTreeWidget#OutlineTree,
+QTreeWidget#SessionHistoryTree {
+    color: ${text_soft};
+    background: ${void};
+    border: 1px solid ${border_strong};
+    border-radius: 4px;
+}
+QTreeWidget#CommandPaletteResults::item,
+QTreeWidget#BundleSearchTree::item,
+QTreeWidget#OutlineTree::item,
+QTreeWidget#SessionHistoryTree::item {
+    border-bottom: 1px solid ${surface_raised};
+    padding: 6px 5px;
+}
+QTreeWidget#CommandPaletteResults::item:hover,
+QTreeWidget#BundleSearchTree::item:hover,
+QTreeWidget#OutlineTree::item:hover,
+QTreeWidget#SessionHistoryTree::item:hover {
+    color: ${text};
+    background: ${surface_hover};
+}
+QTreeWidget#CommandPaletteResults::item:selected,
+QTreeWidget#BundleSearchTree::item:selected,
+QTreeWidget#OutlineTree::item:selected,
+QTreeWidget#SessionHistoryTree::item:selected {
+    color: ${text};
+    background: ${selection};
+    border-left: 3px solid ${blue_bright};
+}
+QWidget#BundleSearchView,
+QWidget#OutlineView,
+QWidget#SessionHistoryView {
+    background: ${canvas};
+}
+QFrame#SourceSplitSurface {
+    background: ${void};
+    border: 1px solid ${border};
+    border-top: 2px solid ${blue_dim};
+    border-radius: 4px;
+}
+QLabel#GeneratedCWindowLabel {
+    color: ${warning_bright};
+    background: ${warning_dim};
+    border: 1px solid ${warm_dim};
+    border-radius: 4px;
+    padding: 3px 8px;
+}
+"""
+)
+
+
+def build_workspace_stylesheet(
+    colors: PyCForgeColors = PYCFORGE_COLORS,
+) -> str:
+    """Return deterministic styling for the Phase 15C workspace surfaces."""
+
+    return _WORKSPACE_QSS.substitute(dict(color_tokens(colors))).strip() + "\n"
+
+
+__all__ = ["build_workspace_stylesheet"]

pycforge_sdk/gui/visual/visual_tokens.py

@@ -0,0 +1,146 @@
+"""Headless-safe semantic tokens for the PyCForge desktop visual system.
+
+The optional Qt workspace and its tests share these values without importing
+Qt.  Colors are named for their role rather than a particular widget so the
+visual language remains coherent across menus, editors, panels, and future
+presentation surfaces.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from types import MappingProxyType
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class PyCForgeColors:
+    """Matte graphite palette with readable silver text and steel-blue accents."""
+
+    void: str = "#14191E"
+    canvas: str = "#1B2127"
+    surface: str = "#262D34"
+    surface_raised: str = "#303840"
+    surface_active: str = "#39444E"
+    surface_hover: str = "#45535F"
+    border: str = "#4C5965"
+    border_strong: str = "#667783"
+    text: str = "#E0E5E9"
+    text_soft: str = "#CAD3DA"
+    text_muted: str = "#A7B4BE"
+    text_disabled: str = "#95A1AB"
+    blue: str = "#88ABC4"
+    blue_bright: str = "#A6C8DF"
+    blue_dim: str = "#2C3D4B"
+    cyan: str = "#8EAEB9"
+    cyan_bright: str = "#B2CDD5"
+    cyan_dim: str = "#2D4148"
+    violet: str = "#9BA5B7"
+    violet_bright: str = "#BBC4D3"
+    violet_dim: str = "#39404D"
+    warm: str = "#BA946F"
+    warm_bright: str = "#D3B393"
+    warm_dim: str = "#44382C"
+    success: str = "#81AB96"
+    success_bright: str = "#ADD0BD"
+    success_dim: str = "#23372D"
+    warning: str = "#B9A172"
+    warning_bright: str = "#DAC393"
+    warning_dim: str = "#373024"
+    error: str = "#BE858A"
+    error_bright: str = "#E0AFB3"
+    error_dim: str = "#38252B"
+    selection: str = "#324656"
+    selection_active: str = "#40596D"
+    focus_ring: str = "#9AC3DE"
+
+
+@dataclass(frozen=True, slots=True)
+class PyCForgeMetrics:
+    """Logical-pixel metrics; Qt applies the effective display scale."""
+
+    radius_small: int = 4
+    radius_control: int = 4
+    radius_panel: int = 5
+    radius_menu: int = 5
+    icon_menu: int = 18
+    icon_toolbar: int = 20
+    icon_navigator: int = 18
+    toolbar_button_height: int = 33
+    compact_header_font_point_size: int = 9
+    compact_header_control_size: int = 28
+    compact_header_icon_size: int = 18
+    focus_width: int = 2
+    menu_outer_padding: int = 6
+    menu_item_vertical_padding: int = 7
+    menu_item_left_padding: int = 38
+    menu_item_right_padding: int = 36
+
+
+PYCFORGE_COLORS = PyCForgeColors()
+PYCFORGE_METRICS = PyCForgeMetrics()
+
+
+def color_tokens(
+    colors: PyCForgeColors = PYCFORGE_COLORS,
+) -> Mapping[str, str]:
+    """Return an immutable token mapping suitable for stylesheet expansion."""
+
+    return MappingProxyType(asdict(colors))
+
+
+def relative_luminance(color: str) -> float:
+    """Return WCAG relative luminance for an exact ``#RRGGBB`` color."""
+
+    red, green, blue = _rgb_channels(color)
+    linear = tuple(
+        channel / 12.92
+        if channel <= 0.04045
+        else ((channel + 0.055) / 1.055) ** 2.4
+        for channel in (red, green, blue)
+    )
+    return (
+        0.2126 * linear[0]
+        + 0.7152 * linear[1]
+        + 0.0722 * linear[2]
+    )
+
+
+def contrast_ratio(first: str, second: str) -> float:
+    """Return the WCAG contrast ratio between two exact RGB colors."""
+
+    lighter, darker = sorted(
+        (relative_luminance(first), relative_luminance(second)),
+        reverse=True,
+    )
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def _rgb_channels(color: str) -> tuple[float, float, float]:
+    if (
+        not isinstance(color, str)
+        or len(color) != 7
+        or not color.startswith("#")
+    ):
+        raise ValueError("color must use exact #RRGGBB notation")
+    try:
+        values = tuple(
+            int(color[index : index + 2], 16) / 255.0
+            for index in (1, 3, 5)
+        )
+    except ValueError as exc:
+        raise ValueError(
+            "color must use exact #RRGGBB notation"
+        ) from exc
+    return values  # type: ignore[return-value]
+
+
+__all__ = [
+    "PYCFORGE_COLORS",
+    "PYCFORGE_METRICS",
+    "PyCForgeColors",
+    "PyCForgeMetrics",
+    "color_tokens",
+    "contrast_ratio",
+    "relative_luminance",
+]

pycforge_sdk/gui/widgets.py

@@ -0,0 +1,68 @@
+"""Small presentation helpers using PyCForge's preserved visual components."""
+from html import escape
+from PySide6.QtCore import Qt, QSize
+from PySide6.QtWidgets import QLabel, QPushButton, QTextBrowser, QProxyStyle, QStyle, QStyleFactory
+from .visual.qt_icons import load_pycforge_icon
+
+
+def label(text, *, muted=False):
+    item = QLabel(text)
+    item.setTextFormat(Qt.TextFormat.PlainText)
+    item.setWordWrap(True)
+    if muted:
+        item.setObjectName("MutedLabel")
+    return item
+
+
+def button(text, icon, callback, tip=""):
+    item = QPushButton(load_pycforge_icon(icon), text)
+    item.setIconSize(QSize(20, 20))
+    item.setAccessibleName(text.replace("&", ""))
+    item.setToolTip(tip or text.replace("&", ""))
+    item.clicked.connect(callback)
+    return item
+
+
+class MenuIconStyle(QProxyStyle):
+    """Use the full 24-pixel artwork in SDK menu rows at every display scale."""
+    def __init__(self, parent):
+        super().__init__(QStyleFactory.create('Fusion'))
+        self.setParent(parent)
+
+    def pixelMetric(self, metric, option=None, widget=None):
+        if metric == QStyle.PixelMetric.PM_SmallIconSize:
+            return 24
+        return super().pixelMetric(metric, option, widget)
+
+
+class SafeBrowser(QTextBrowser):
+    """Inert text/reference display: no external navigation or resource loads."""
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setOpenLinks(False)
+        self.setOpenExternalLinks(False)
+
+    def loadResource(self, resource_type, url):
+        return None
+
+
+def method_html(entry):
+    def text(value):
+        return escape(str(value)).replace("\n", "<br>")
+    parts = ["<h2>" + text(entry.get("title", "Reference")) + "</h2>",
+             "<p>" + text(entry.get("summary", "")) + "</p>",
+             "<pre>" + text(entry.get("public_path", "") + entry.get("signature", "")) + "</pre>"]
+    for p in entry.get("parameters", []):
+        parts.append("<p><b>" + text(p["name"]) + "</b> — " + text(p["description"]) + "</p>")
+        if p.get("choices"):
+            parts.append("<p>Choices: " + text(", ".join(map(str, p["choices"]))) + "</p>")
+    for key in ("returns", "effects", "limits"):
+        value = entry.get(key, "")
+        if isinstance(value, list): value = "\n".join(value)
+        parts.append("<h3>" + key.title() + "</h3><p>" + text(value) + "</p>")
+    for error in entry.get("errors", []):
+        parts.append("<p><b>" + text(error.get("code", "")) + "</b> " +
+                     text(error.get("meaning", "")) + " " + text(error.get("remedy", "")) + "</p>")
+    for example in entry.get("examples", []):
+        parts.append("<pre>" + text(example) + "</pre>")
+    return "".join(parts)