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.
