sli-ui-toolkit 0.2.7__tar.gz

sli_ui_toolkit-0.2.7/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: sli-ui-toolkit
+Version: 0.2.7
+Summary: Reusable PyQt UI toolkit primitives for SLI desktop tools.
+Author: Loganavter
+License: MIT
+Project-URL: Repository, https://github.com/Loganavter/sli-ui-toolkit
+Project-URL: Issues, https://github.com/Loganavter/sli-ui-toolkit/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyQt6>=6.6
+Requires-Dist: markdown>=3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-qt>=4.2; extra == "dev"
+
+# SLI UI Toolkit
+
+`sli-ui-toolkit` is a reusable PyQt6 widget and UI-support library.
+SLI stands for **Shared Lightweight Interface**.
+
+It was extracted from two production apps, Improve-ImgSLI and Tkonverter.
+That history is still visible in some widget choices and naming, but the
+package is maintained as a general-purpose toolkit: host-specific behavior is
+kept outside the library and injected through configuration hooks.
+
+Use it when you want:
+
+- custom-painted compact controls;
+- a unified button system;
+- theme-aware widgets and flyouts;
+- app-injected icons, translations, and overlay behavior.
+
+## Start Here
+
+This file is the integration entry point, not the full reference.
+
+- Full public API: [docs/API_CATALOG.md](docs/API_CATALOG.md)
+- Internal structure: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Visual conventions: [docs/DESIGN_LANGUAGE.md](docs/DESIGN_LANGUAGE.md)
+- Docs index: [docs/README.md](docs/README.md)
+
+## Import Layers
+
+Use these import layers on purpose:
+
+- `sli_ui_toolkit`
+  Small top-level bootstrap surface.
+- `sli_ui_toolkit.widgets`
+  Main public widget catalog.
+- `sli_ui_toolkit.i18n`
+  Translation manager and helpers.
+- `sli_ui_toolkit.icons`
+  Icon resolver configuration.
+- `sli_ui_toolkit.theme`
+  Theme manager.
+- `sli_ui_toolkit.managers`
+  Flyout and timer helpers.
+- `sli_ui_toolkit.services`
+  Utility services such as prewarm helpers.
+
+If you are building app UI, most of the time you want `sli_ui_toolkit.widgets`.
+
+## Configuration Hooks
+
+App-specific behavior is injected at startup:
+
+- `configure_icon_resolver(...)`
+- `configure_toolkit(...)`
+- `configure_i18n(...)`
+
+These hooks keep the toolkit reusable while letting the host app supply:
+
+- icon lookup;
+- translation roots;
+- overlay-layer resolution;
+- timing constants.
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout
+
+from sli_ui_toolkit import FlyoutTimingConfig, configure_i18n, configure_toolkit
+from sli_ui_toolkit.icons import configure_icon_resolver
+from sli_ui_toolkit.theme import ThemeManager
+from sli_ui_toolkit.widgets import Button, ComboBox, install_application_tooltips
+
+app = QApplication([])
+
+theme = ThemeManager.get_instance()
+theme.register_palettes(light_palette={...}, dark_palette={...})
+theme.register_qss_path(str(Path("resources/qss/app.qss")))
+theme.set_theme("light", app)
+
+configure_icon_resolver(resolver=my_icon_lookup)
+
+configure_toolkit(
+    timings=FlyoutTimingConfig(
+        transient_auto_hide_delay_ms=300,
+        flyout_animation_duration_ms=150,
+        text_settings_flyout_animation_duration_ms=150,
+    ),
+    overlay_resolver=lambda widget: getattr(widget.window(), "overlay_layer", None),
+)
+
+configure_i18n(i18n_root=Path("resources/i18n"))
+install_application_tooltips(app)
+
+window = QWidget()
+layout = QVBoxLayout(window)
+
+save_button = Button("save", text="Save", variant="primary")
+mode_combo = ComboBox()
+mode_combo.addItems(["Fast", "Balanced", "Quality"])
+
+layout.addWidget(save_button)
+layout.addWidget(mode_combo)
+window.show()
+
+app.exec()
+```
+
+Flyouts, button dropdown menus, and similar in-window surfaces use
+`overlay_resolver` when a host app provides an overlay layer. The resolved
+object should expose `host`, `attach(widget)`, `anchor_rect(anchor)`, and
+`clamp_rect(rect, margin=...)`. If no overlay layer is resolved, button dropdown
+menus fall back to the top-level window and position themselves in window
+coordinates. Menu surfaces are painted from `flyout.background` /
+`flyout.border`; individual rows only use `list_item.background.hover` for the
+hovered or current item.
+
+## First Widgets To Reach For
+
+- `Button`
+  Unified icon/text/toggle/menu/scrollable button system.
+- `ComboBox`
+  Custom-painted combo box with popup, search, and keyboard navigation.
+- `CustomLineEdit`
+  Themed editable text field.
+- `SidebarDialogShell`
+  Settings/help style dialog shell.
+- `ScrollableDialogPage`
+  Scrollable dialog page container.
+- `MarkdownHelpDialog`
+  Reusable markdown help/documentation dialog.
+
+Usage details live in [docs/API_CATALOG.md](docs/API_CATALOG.md).
+
+## Notes
+
+- `ComboBox` is a custom widget, not a full `QComboBox` drop-in replacement.
+- The toolkit is designed around custom-painted controls, not QSS-skinned stock widgets.
+- App-specific icons and translations should stay outside the toolkit and be injected through configuration.

sli_ui_toolkit-0.2.7/README.md

@@ -0,0 +1,140 @@
+# SLI UI Toolkit
+
+`sli-ui-toolkit` is a reusable PyQt6 widget and UI-support library.
+SLI stands for **Shared Lightweight Interface**.
+
+It was extracted from two production apps, Improve-ImgSLI and Tkonverter.
+That history is still visible in some widget choices and naming, but the
+package is maintained as a general-purpose toolkit: host-specific behavior is
+kept outside the library and injected through configuration hooks.
+
+Use it when you want:
+
+- custom-painted compact controls;
+- a unified button system;
+- theme-aware widgets and flyouts;
+- app-injected icons, translations, and overlay behavior.
+
+## Start Here
+
+This file is the integration entry point, not the full reference.
+
+- Full public API: [docs/API_CATALOG.md](docs/API_CATALOG.md)
+- Internal structure: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Visual conventions: [docs/DESIGN_LANGUAGE.md](docs/DESIGN_LANGUAGE.md)
+- Docs index: [docs/README.md](docs/README.md)
+
+## Import Layers
+
+Use these import layers on purpose:
+
+- `sli_ui_toolkit`
+  Small top-level bootstrap surface.
+- `sli_ui_toolkit.widgets`
+  Main public widget catalog.
+- `sli_ui_toolkit.i18n`
+  Translation manager and helpers.
+- `sli_ui_toolkit.icons`
+  Icon resolver configuration.
+- `sli_ui_toolkit.theme`
+  Theme manager.
+- `sli_ui_toolkit.managers`
+  Flyout and timer helpers.
+- `sli_ui_toolkit.services`
+  Utility services such as prewarm helpers.
+
+If you are building app UI, most of the time you want `sli_ui_toolkit.widgets`.
+
+## Configuration Hooks
+
+App-specific behavior is injected at startup:
+
+- `configure_icon_resolver(...)`
+- `configure_toolkit(...)`
+- `configure_i18n(...)`
+
+These hooks keep the toolkit reusable while letting the host app supply:
+
+- icon lookup;
+- translation roots;
+- overlay-layer resolution;
+- timing constants.
+
+## Quick Start
+
+```python
+from pathlib import Path
+
+from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout
+
+from sli_ui_toolkit import FlyoutTimingConfig, configure_i18n, configure_toolkit
+from sli_ui_toolkit.icons import configure_icon_resolver
+from sli_ui_toolkit.theme import ThemeManager
+from sli_ui_toolkit.widgets import Button, ComboBox, install_application_tooltips
+
+app = QApplication([])
+
+theme = ThemeManager.get_instance()
+theme.register_palettes(light_palette={...}, dark_palette={...})
+theme.register_qss_path(str(Path("resources/qss/app.qss")))
+theme.set_theme("light", app)
+
+configure_icon_resolver(resolver=my_icon_lookup)
+
+configure_toolkit(
+    timings=FlyoutTimingConfig(
+        transient_auto_hide_delay_ms=300,
+        flyout_animation_duration_ms=150,
+        text_settings_flyout_animation_duration_ms=150,
+    ),
+    overlay_resolver=lambda widget: getattr(widget.window(), "overlay_layer", None),
+)
+
+configure_i18n(i18n_root=Path("resources/i18n"))
+install_application_tooltips(app)
+
+window = QWidget()
+layout = QVBoxLayout(window)
+
+save_button = Button("save", text="Save", variant="primary")
+mode_combo = ComboBox()
+mode_combo.addItems(["Fast", "Balanced", "Quality"])
+
+layout.addWidget(save_button)
+layout.addWidget(mode_combo)
+window.show()
+
+app.exec()
+```
+
+Flyouts, button dropdown menus, and similar in-window surfaces use
+`overlay_resolver` when a host app provides an overlay layer. The resolved
+object should expose `host`, `attach(widget)`, `anchor_rect(anchor)`, and
+`clamp_rect(rect, margin=...)`. If no overlay layer is resolved, button dropdown
+menus fall back to the top-level window and position themselves in window
+coordinates. Menu surfaces are painted from `flyout.background` /
+`flyout.border`; individual rows only use `list_item.background.hover` for the
+hovered or current item.
+
+## First Widgets To Reach For
+
+- `Button`
+  Unified icon/text/toggle/menu/scrollable button system.
+- `ComboBox`
+  Custom-painted combo box with popup, search, and keyboard navigation.
+- `CustomLineEdit`
+  Themed editable text field.
+- `SidebarDialogShell`
+  Settings/help style dialog shell.
+- `ScrollableDialogPage`
+  Scrollable dialog page container.
+- `MarkdownHelpDialog`
+  Reusable markdown help/documentation dialog.
+
+Usage details live in [docs/API_CATALOG.md](docs/API_CATALOG.md).
+
+## Notes
+
+- `ComboBox` is a custom widget, not a full `QComboBox` drop-in replacement.
+- The toolkit is designed around custom-painted controls, not QSS-skinned stock widgets.
+- App-specific icons and translations should stay outside the toolkit and be injected through configuration.

sli_ui_toolkit-0.2.7/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sli-ui-toolkit"
+version = "0.2.7"
+description = "Reusable PyQt UI toolkit primitives for SLI desktop tools."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "PyQt6>=6.6",
+    "markdown>=3.4",
+]
+license = { text = "MIT" }
+authors = [
+    { name = "Loganavter" },
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-qt>=4.2",
+]
+
+[project.urls]
+Repository = "https://github.com/Loganavter/sli-ui-toolkit"
+Issues = "https://github.com/Loganavter/sli-ui-toolkit/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"sli_ui_toolkit" = ["resources/assets/icons/*.svg", "resources/assets/icons/light/*.svg", "resources/assets/icons/dark/*.svg"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

sli_ui_toolkit-0.2.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sli_ui_toolkit-0.2.7/src/sli_ui_toolkit/__init__.py

@@ -0,0 +1,72 @@
+"""Reusable PyQt toolkit primitives."""
+
+from sli_ui_toolkit._version import __version__
+from sli_ui_toolkit.config import FlyoutTimingConfig, configure_toolkit
+from sli_ui_toolkit.palettes import FLUENT_LIGHT, FLUENT_DARK
+from sli_ui_toolkit.core.logging import (
+    get_log_directory,
+    setup_logging,
+    setup_simple_logging,
+)
+from sli_ui_toolkit.i18n import (
+    ToolkitTranslationEvents,
+    TranslationManager,
+    configure_i18n,
+    emit_language_changed,
+    get_current_language,
+    tr,
+    translation_events,
+)
+from sli_ui_toolkit.utils.file_utils import get_unique_filepath
+from sli_ui_toolkit.utils.paths import resource_path
+from sli_ui_toolkit.workers.generic_worker import GenericWorker, WorkerSignals
+from sli_ui_toolkit.theme import ThemeManager
+from sli_ui_toolkit.widgets import (
+    Label,
+    LabelConfig,
+    LabelVariantSpec,
+    application_tooltips_enabled,
+    get_label_variant,
+    install_application_tooltips,
+    register_label_variant,
+    set_application_tooltips_enabled,
+)
+from sli_ui_toolkit.style import (
+    WidgetStyleTokens,
+    read_widget_style,
+    update_widget_style,
+)
+
+__all__ = [
+    "__version__",
+    "GenericWorker",
+    "WorkerSignals",
+    "ThemeManager",
+    "Label",
+    "LabelConfig",
+    "LabelVariantSpec",
+    "get_label_variant",
+    "register_label_variant",
+    "application_tooltips_enabled",
+    "install_application_tooltips",
+    "set_application_tooltips_enabled",
+    "WidgetStyleTokens",
+    "read_widget_style",
+    "update_widget_style",
+    "FlyoutTimingConfig",
+    "ToolkitTranslationEvents",
+    "TranslationManager",
+    "configure_i18n",
+    "configure_toolkit",
+    "emit_language_changed",
+    "get_log_directory",
+    "get_current_language",
+    "get_unique_filepath",
+    "resource_path",
+    "setup_logging",
+    "setup_simple_logging",
+    "tr",
+    "translation_events",
+    "FLUENT_LIGHT",
+    "FLUENT_DARK",
+]

sli_ui_toolkit-0.2.7/src/sli_ui_toolkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.7"

sli_ui_toolkit-0.2.7/src/sli_ui_toolkit/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+@dataclass(slots=True)
+class FlyoutTimingConfig:
+    transient_auto_hide_delay_ms: int = 180
+    flyout_animation_duration_ms: int = 160
+    text_settings_flyout_animation_duration_ms: int = 180
+
+_timings = FlyoutTimingConfig()
+_overlay_resolver: Callable[[object | None], object | None] | None = None
+_rating_gesture_factory: Callable[..., object] | None = None
+_dragdrop_service_getter: Callable[[], object | None] | None = None
+
+def configure_toolkit(
+    *,
+    timings: FlyoutTimingConfig | None = None,
+    overlay_resolver: Callable[[object | None], object | None] | None = None,
+    rating_gesture_factory: Callable[..., object] | None = None,
+    dragdrop_service_getter: Callable[[], object | None] | None = None,
+) -> None:
+    global _timings, _overlay_resolver, _rating_gesture_factory, _dragdrop_service_getter
+    if timings is not None:
+        _timings = timings
+    if overlay_resolver is not None:
+        _overlay_resolver = overlay_resolver
+    if rating_gesture_factory is not None:
+        _rating_gesture_factory = rating_gesture_factory
+    if dragdrop_service_getter is not None:
+        _dragdrop_service_getter = dragdrop_service_getter
+
+def get_flyout_timings() -> FlyoutTimingConfig:
+    return _timings
+
+def resolve_overlay_layer(widget: object | None):
+    if _overlay_resolver is None:
+        return None
+    try:
+        return _overlay_resolver(widget)
+    except Exception:
+        return None
+
+def create_rating_gesture(**kwargs):
+    if _rating_gesture_factory is None:
+        return None
+    try:
+        return _rating_gesture_factory(**kwargs)
+    except Exception:
+        return None
+
+def get_dragdrop_service():
+    if _dragdrop_service_getter is None:
+        from sli_ui_toolkit.ui.services.dragdrop_service import ToolkitDragDropService
+
+        return ToolkitDragDropService.get_instance()
+    try:
+        return _dragdrop_service_getter()
+    except Exception:
+        from sli_ui_toolkit.ui.services.dragdrop_service import ToolkitDragDropService
+
+        return ToolkitDragDropService.get_instance()

sli_ui_toolkit-0.2.7/src/sli_ui_toolkit/core/__init__.py

@@ -0,0 +1,7 @@
+from sli_ui_toolkit.core.logging import (
+    get_log_directory,
+    setup_logging,
+    setup_simple_logging,
+)
+
+__all__ = ["get_log_directory", "setup_logging", "setup_simple_logging"]

sli_ui_toolkit-0.2.7/src/sli_ui_toolkit/core/logging.py

@@ -0,0 +1,99 @@
+import logging
+import os
+import sys
+
+def get_log_directory(app_name: str) -> str:
+    logger = logging.getLogger(app_name)
+
+    if sys.platform == "win32":
+        app_data_dir = os.getenv("APPDATA")
+        if not app_data_dir:
+            app_data_dir = os.path.expanduser("~")
+            logger.warning(
+                "Could not find APPDATA env variable, falling back to home directory."
+            )
+        return os.path.join(app_data_dir, app_name)
+
+    if sys.platform == "darwin":
+        return os.path.join(
+            os.path.expanduser("~/Library/Application Support"), app_name
+        )
+
+    xdg_data_home = os.getenv("XDG_DATA_HOME", os.path.expanduser("~/.local/share"))
+    return os.path.join(xdg_data_home, app_name)
+
+def setup_logging(
+    app_name: str, debug_enabled: bool = False, debug_env_var: str | None = None
+) -> None:
+    logger = logging.getLogger(app_name)
+
+    if debug_env_var:
+        suppress_debug = (
+            os.getenv(f"{debug_env_var.replace('_DEBUG', '_SUPPRESS_DEBUG')}", "0")
+            == "1"
+        )
+        if suppress_debug:
+            debug_enabled = False
+        elif os.getenv(debug_env_var, "0") == "1":
+            debug_enabled = True
+
+    level = logging.DEBUG if debug_enabled else logging.INFO
+
+    if logger.handlers:
+        logger.setLevel(level)
+        for handler in logger.handlers:
+            handler.setLevel(level)
+        return
+
+    logger.setLevel(level)
+    formatter = logging.Formatter(
+        "%(asctime)s - [%(levelname)s] - (%(filename)s:%(lineno)d) - %(message)s"
+    )
+
+    stream_handler = logging.StreamHandler(sys.stdout)
+    stream_handler.setFormatter(formatter)
+    stream_handler.setLevel(level)
+    logger.addHandler(stream_handler)
+
+    try:
+        log_dir = get_log_directory(app_name)
+        os.makedirs(log_dir, exist_ok=True)
+        log_file_path = os.path.join(log_dir, "log.txt")
+
+        file_handler = logging.FileHandler(log_file_path, mode="w", encoding="utf-8")
+        file_handler.setFormatter(formatter)
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+
+        logging.getLogger("markdown").setLevel(logging.WARNING)
+        logging.getLogger("markdown.extensions").setLevel(logging.WARNING)
+    except Exception:
+        logger.error(
+            "FATAL: Failed to set up file logger. Continuing with console-only logging.",
+            exc_info=True,
+        )
+
+def setup_simple_logging(app_name: str, level: int = logging.WARNING) -> None:
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+
+    root_logger.addHandler(console_handler)
+
+    app_logger = logging.getLogger(app_name)
+    app_logger.setLevel(level)
+
+    logging.getLogger("markdown").setLevel(logging.WARNING)
+    logging.getLogger("markdown.extensions").setLevel(logging.WARNING)
+