UI Panels

Config-driven helpers that create Rich panels with consistent styling. PanelManager merges defaults, presets, and runtime overrides so dashboards keep coherent framing without hand-writing Rich code.

Tip

See Panels for the feature guide.

Quick overview

  • Defaults provide a neutral box (ROUNDED), bright blue border, and key/value table layout for mapping payloads.

  • Presets (info, success, warning, error, summary) modify titles, icons, and content styles; you can extend them via ui.panels.presets in kstlib.conf.yml.

  • Payloads accept strings, Rich renderables, mappings, sequences of (key, value), or None.

  • print_panel_async delegates to asyncio.to_thread so event loops stay responsive.

Configuration snippet

ui:
    panels:
        defaults:
            panel:
                border_style: "bright_blue"
                box: "ROUNDED"
                padding: [1, 2]
            content:
                box: "SIMPLE"
                show_header: false
                key_style: "bold white"
                value_style: null
                sort_keys: false
        presets:
            summary:
                panel:
                    border_style: "light_steel_blue1"
                    title: "Execution Summary"
                    icon: "📝"
                content:
                    sort_keys: true
                    key_style: "bold orchid2"
                    value_style: "dim white"

Usage patterns

Basic rendering

from kstlib.ui.panels import PanelManager

manager = PanelManager()
manager.print_panel(payload={"status": "running", "jobs": 3})
manager.print_panel(kind="info", payload="System ready")

Custom presets

custom_config = {
    "presets": {
        "alerts": {
            "panel": {"title": "Alerts", "border_style": "red3", "icon": "[alert]"},
            "content": {"use_markup": True},
        }
    }
}

manager = PanelManager(config=custom_config)
manager.print_panel(kind="alerts", payload="[bold red]Risk warning[/bold red]")

Async-friendly printing

import asyncio
from kstlib.ui.panels import PanelManager

async def main() -> None:
    manager = PanelManager()
    await manager.print_panel_async(kind="summary", payload={"orders": 128, "errors": 1})

asyncio.run(main())

Embedding Rich tables

from kstlib.ui import TableBuilder
from kstlib.ui.panels import PanelManager

builder = TableBuilder()
manager = PanelManager()
payload = builder.render_table(kind="inventory", data=[{"component": "cache", "status": "ok"}])
manager.print_panel(kind="summary", payload=payload)

Module reference

Config-driven helpers for rendering Rich panels.

class kstlib.ui.panels.PanelManager(config=None, console=None)[source]

Bases: object

Render Rich panels using config-driven presets.

Panel definitions are composed of defaults, named presets, and runtime overrides. The merge order is kwargs > config preset > defaults. Payloads can be plain text, existing Rich renderables, mappings (rendered as two-column tables), or sequences of (key, value) pairs.

Parameters:

  • config (Mapping[str, Any] | Box | None) – Optional configuration mapping (typically output of get_config()).

  • console (Console | None) – Optional Rich console used for printing panels.

console

Console instance used for synchronous printing.

Examples

Create a panel manager:

>>> pm = PanelManager()
>>> pm.console is None
True

Render a simple text panel:

>>> panel = pm.render_panel(payload="Hello, World!")
>>> panel.title is None
True

Render with a preset:

>>> panel = pm.render_panel("info", payload="System status: OK")
>>> "Information" in str(panel.title)
True

Render a mapping as a table:

>>> panel = pm.render_panel(payload={"name": "Alice", "age": 30})

Override preset values:

>>> panel = pm.render_panel("error", payload="Oops!", title="Custom Title")
>>> "Custom Title" in str(panel.title)
True
__init__(self, config: 'Mapping[str, Any] | Box | None' = None, console: 'Console | None' = None) → 'None' -> None[source]

Initialize the manager with optional config and console.

render_panel(self, kind: 'str | None' = None, payload: 'PanelPayload' = None, **overrides: 'Any') → 'Panel' -> Panel[source]

Build a Panel instance without printing it.

Parameters:

  • kind (str | None) – Name of the preset to use. If not found, defaults are used.

  • payload (ConsoleRenderable | RichCast | str | Mapping[str, Any] | Sequence[tuple[Any, Any]] | None) – Panel body (text, Rich renderable, mapping, or sequence of pairs).

  • **overrides (Any) – Runtime overrides applied on top of preset/default values.

Returns:

Configured Rich Panel ready for rendering.

Raises:

PanelRenderingError – If the payload type is unsupported.

Return type:

Panel

print_panel(self, kind: 'str | None' = None, payload: 'PanelPayload' = None, *, console: 'Console | None' = None, **overrides: 'Any') → 'Panel' -> Panel[source]

Render and print a panel synchronously.

Parameters:

  • kind (str | None) – Name of the preset to use.

  • payload (ConsoleRenderable | RichCast | str | Mapping[str, Any] | Sequence[tuple[Any, Any]] | None) – Panel body.

  • console (Console | None) – Optional console overriding the manager-level console.

  • **overrides (Any) – Runtime overrides applied on top of preset/default values.

Returns:

The rendered Panel.

Return type:

Panel

async print_panel_async(self, kind: 'str | None' = None, payload: 'PanelPayload' = None, *, console: 'Console | None' = None, **overrides: 'Any') → 'Panel' -> Panel[source]

Render and print a panel using an executor for async compatibility.

Parameters:

  • kind (str | None) – Name of the preset to use.

  • payload (ConsoleRenderable | RichCast | str | Mapping[str, Any] | Sequence[tuple[Any, Any]] | None) – Panel body.

  • console (Console | None) – Optional console overriding the manager-level console.

  • **overrides (Any) – Runtime overrides applied on top of preset/default values.

Returns:

The rendered Panel.

Return type:

Panel