Views¶
Immutable navigation, result, detail, status, and selection models rendered by the workbench. The page guide maps information shapes to useful views.
Paginated tables¶
Use Pagination when a page owns a bounded query result and needs to expose the result's position without making pagination a database or workbench concern:
pagination = Pagination(page=2, page_size=20, total_items=41)
view = TableView(
title="Mapping review",
columns=("Source", "Status"),
rows=rows,
pagination=pagination,
actions=pagination_actions(pagination),
)
pagination_actions supplies disabled-aware previous/next commands. The page still owns the handlers and the query; Groundskeeping only renders the metadata and stable table chrome.
TableRow.key remains the stable row identity. Pages can use it to handle a selected row, open a wizard, or apply a later validation/acceptance action. The base TableView intentionally does not embed editable controls, so adding a specialised row editor later will not change the existing table or pagination contract.
Generic presentation models rendered by the shared workbench.
ViewActionVariant ¶
ViewActionVariant = Literal[
"default", "primary", "success", "warning", "error"
]
CatalogueItem
dataclass
¶
CatalogueItem(
key: str,
label: str,
kind: str,
ref: object | None = None,
status: SemanticStatus = SemanticStatus.INFO,
children: tuple[CatalogueItem, ...] = (),
)
One navigable item in a page's catalogue tree.
CatalogueNavigation
dataclass
¶
CatalogueNavigation(
items: tuple[CatalogueItem, ...],
title: str = "Catalogue",
)
EmptyView
dataclass
¶
EmptyView(
title: str,
message: str,
status: SemanticStatus = SemanticStatus.IDLE,
command: str | None = None,
actions: tuple[ViewAction, ...] = (),
)
A surface view explaining that no rows are available.
KeyValueView
dataclass
¶
KeyValueView(
rows: tuple[tuple[str, str], ...], title: str = "Detail"
)
LoadingView
dataclass
¶
LoadingView(
title: str,
message: str,
detail: str | None = None,
command: str | None = None,
actions: tuple[ViewAction, ...] = (),
)
A surface view for in-progress page work.
Pagination
dataclass
¶
Pagination(page: int, page_size: int, total_items: int)
Page metadata for a bounded table result.
page_count
property
¶
page_count: int
Return at least one page so empty results have a stable display.
SectionItem
dataclass
¶
SectionItem(
key: str,
label: str,
status: SemanticStatus = SemanticStatus.INFO,
description: str | None = None,
)
SectionNavigation
dataclass
¶
SectionNavigation(
items: tuple[SectionItem, ...], title: str = "Sections"
)
SelectionTableRow
dataclass
¶
SelectionTableRow(
key: str,
cells: tuple[str, ...],
selected: bool = False,
disabled: bool = False,
selection_group: str | None = None,
detail: object | None = None,
)
One selectable row in a workbench-owned selection table.
SelectionTableView
dataclass
¶
SelectionTableView(
title: str,
columns: tuple[str, ...],
rows: tuple[SelectionTableRow, ...],
status: SemanticStatus = SemanticStatus.INFO,
message: str | None = None,
actions: tuple[ViewAction, ...] = (),
selection_mode: SelectionMode = "multiple",
all_row_key: str | None = None,
)
A table-shaped surface where Groundskeeping owns row toggle semantics.
SemanticStatus ¶
Bases: StrEnum
Small health/status vocabulary understood by shared widgets.
TableRow
dataclass
¶
TableRow(
key: str,
cells: tuple[str, ...],
detail: object | None = None,
)
One row in a selectable workbench table.
Row interaction remains page-owned: key identifies the row for actions,
selection, and validation workflows, while detail may carry the payload
shown after selection. Inline editors are deliberately not part of the base
table contract; pages can open a wizard or use a selection table instead.
TableView
dataclass
¶
TableView(
title: str,
columns: tuple[str, ...],
rows: tuple[TableRow, ...],
status: SemanticStatus = SemanticStatus.INFO,
message: str | None = None,
actions: tuple[ViewAction, ...] = (),
pagination: Pagination | None = None,
)
A table-shaped surface view.
TableRow.key is the stable identity used by the workbench when a consumer calls
its refresh API. Keep keys stable for rows that remain in the underlying data set so
the operator's cursor can follow the same row as cells and row membership change.
TextView
dataclass
¶
TextView(title: str, body: str)
TreeNode
dataclass
¶
TreeNode(
label: str,
status: SemanticStatus = SemanticStatus.INFO,
fields: Mapping[str, object] = dict(),
children: tuple[TreeNode, ...] = (),
)
A tree-shaped detail node.
fields
class-attribute
instance-attribute
¶
fields: Mapping[str, object] = field(default_factory=dict)
TreeView
dataclass
¶
TreeView(
title: str,
rows: tuple[TreeNode, ...] = (),
status: SemanticStatus = SemanticStatus.INFO,
message: str | None = None,
notes: tuple[str, ...] = (),
actions: tuple[ViewAction, ...] = (),
)
A nested, heterogeneous surface view.
ViewAction
dataclass
¶
ViewAction(
key: str,
label: str,
variant: ViewActionVariant = "default",
disabled: bool = False,
)
One command rendered with the current workbench view.
The shared workbench renders at most MAX_VIEW_ACTIONS actions. Extra actions remain part
of the view model but are not assigned visible buttons.
WorkbenchLabels
dataclass
¶
WorkbenchLabels(
navigation_panel: str = "Sections",
result_panel: str = "Rows",
detail_panel: str = "Detail",
initial_result_summary: str = "Select a section to inspect it.",
key_value_columns: tuple[str, str] = ("Field", "Value"),
)
Operator-facing labels for reusable workbench chrome.
Page-owned content still supplies its own titles through navigation and view contracts. These labels only cover structural defaults in the shared shell.
pagination_actions ¶
pagination_actions(
pagination: Pagination,
*,
previous_key: str = "pagination.previous",
next_key: str = "pagination.next",
) -> tuple[ViewAction, ...]
Return standard page-navigation actions for a table view.