Widgets

Textual renderers for the workbench, primitive views, and normalized telemetry. Pass them presentation-safe contracts rather than application service objects.

Catalogue, rows, and detail surface shared by consumer-owned pages.

Workbench

Workbench(labels: WorkbenchLabels | None = None)

Bases: Widget

Shared page surface with navigation left and rows/detail right.

catalogue property

catalogue: Tree[Any]

is_showing_loading property

is_showing_loading: bool

labels instance-attribute

labels = labels or WorkbenchLabels()

rows_table property

rows_table: _WorkbenchDataTable

sections property

sections: OptionList

selection_table property

selection_table: SelectionList[str]

SelectionChanged

SelectionChanged(
    workbench: Workbench,
    row_key: str,
    selected_keys: tuple[str, ...],
)

Bases: Message

Posted when a workbench-owned selection table changes selected row keys.

control property

control: Workbench

row_key instance-attribute

row_key = row_key

selected_keys instance-attribute

selected_keys = selected_keys

workbench instance-attribute

workbench = workbench

SelectionHighlighted

SelectionHighlighted(workbench: Workbench, row_key: str)

Bases: Message

Posted when the highlighted row changes in a selection table.

control property

control: Workbench

row_key instance-attribute

row_key = row_key

workbench instance-attribute

workbench = workbench

action_key

action_key(button_id: str | None) -> str | None

compose

compose() -> ComposeResult

on_mount

on_mount() -> None

on_selection_list_selection_highlighted

on_selection_list_selection_highlighted(
    event: SelectionHighlighted[str],
) -> None

on_selection_list_selection_toggled

on_selection_list_selection_toggled(
    event: SelectionToggled[str],
) -> None

populate_catalogue

populate_catalogue(items: Sequence[CatalogueItem]) -> None

refresh_rows

refresh_rows(view: TableView) -> None

Reconcile table rows in place while preserving the highlighted row by key.

Existing cells are updated without rebuilding the DataTable. Added and removed rows are reconciled by their stable keys; if the highlighted row disappears, the cursor stays at its previous position where possible. Cursor changes caused by this reconciliation are deliberately silent, so a refresh cannot re-enter a page's row_highlighted handler.

refresh_view

refresh_view(view: SurfaceView) -> None

Refresh a surface, preserving cursor state when it is a table.

Consumer pages should use this for ordinary data refreshes. Table surfaces reconcile rows in place, and a loading surface already showing another loading view patches its text in place, since a long-running job may refresh this surface many times a second. Every other surface still uses the normal replacement path because it has no in-place identity to retain.

set_status

set_status(status: SemanticStatus | str) -> None

set_summary

set_summary(title: str, message: str | None = None) -> None

show_actions

show_actions(actions: Sequence[ViewAction]) -> None

show_context_table

show_context_table(
    rows: Iterable[tuple[str, str]],
    *,
    columns: tuple[str, ...] | None = None,
) -> None

show_detail

show_detail(detail: DetailView) -> None

show_detail_table

show_detail_table(detail: TableView) -> None

show_empty

show_empty(view: EmptyView) -> None

show_loading

show_loading(view: LoadingView) -> None

show_navigation

show_navigation(navigation: PageNavigation) -> None

show_rows

show_rows(
    view: TableView, *, select_first: bool = True
) -> None

show_selection_rows

show_selection_rows(
    view: SelectionTableView,
    *,
    highlight_first: bool = True,
) -> None

show_surface

show_surface(view: SurfaceView) -> None

show_tree

show_tree(view: TreeView) -> None

update_loading

update_loading(view: LoadingView) -> None

Patch an already-shown loading surface without re-hiding other widgets.

A long-running job may call this many times a second through refresh_view(); only the pieces that actually changed are touched so the result panel does not flicker.

Small stateless widgets used by the shared workbench.

EmptyState

Bases: Static

Placeholder shown where rows would otherwise be rendered.

hide_empty

hide_empty() -> None

show_empty

show_empty(
    message: str, *, command: str | None = None
) -> None

LoadingState

Bases: Static

Frame-driven loading indicator.

FRAMES class-attribute instance-attribute

FRAMES = ('|', '/', '-', '\\')

hide_loading

hide_loading() -> None

show_loading

show_loading(
    message: str,
    *,
    detail: str | None = None,
    command: str | None = None,
    frame: int = 0,
) -> None

Textual widgets that render normalized telemetry snapshots.

TelemetryMetricGrid

Bases: Static

Capability-aware metric grid driven by normalized snapshots.

render_snapshot

render_snapshot(snapshot: TelemetrySnapshot) -> None