Skip to content

Page contracts

Protocols and registrations used by application-owned pages. See Pages and the workbench for lifecycle guidance and view selection.

Page and navigation contracts for consumer-owned operator pages.

NotifySeverity 

NotifySeverity = Literal['information', 'warning', 'error']

Toast severities the shell forwards to Textual's notification system.

OperatorPage

Bases: Protocol

Structural contract implemented by consumer Textual widgets.

route instance-attribute 

route: PageRoute

action_selected 

action_selected(
    action_key: str, context: PageContext
) -> None

activate 

activate(context: PageContext) -> None

build_navigation 

build_navigation(context: PageContext) -> PageNavigation

deactivate 

deactivate(context: PageContext) -> None

landing_view 

landing_view(context: PageContext) -> SurfaceView

navigation_selected 

navigation_selected(
    item: NavigationItem, context: PageContext
) -> None

row_highlighted 

row_highlighted(row_key: str, context: PageContext) -> None

row_selected 

row_selected(row_key: str, context: PageContext) -> None

PageContext

Bases: Protocol

Narrow context passed to page factories.

surface property 

surface: PageSurfacePort

notify 

notify(
    message: str,
    *,
    severity: NotifySeverity = "information",
) -> None

open_wizard 

open_wizard(controller: WizardController) -> None

refresh_bindings 

refresh_bindings() -> None

request_navigation 

request_navigation(page_key: str) -> None

PageRegistration dataclass 

PageRegistration(
    route: PageRoute,
    factory: Callable[[PageContext], OperatorPage],
)

A page route plus the factory that creates the page widget.

factory instance-attribute 

factory: Callable[[PageContext], OperatorPage]

route instance-attribute 

route: PageRoute

PageRegistry 

PageRegistry(routes: Sequence[PageRoute])

Bases: Sequence[PageRoute]

Ordered routes with exact-key lookup and duplicate-key validation.

__getitem__ 

__getitem__(index: int) -> PageRoute

__getitem__(index: slice) -> Sequence[PageRoute]

__getitem__(
    index: int | slice,
) -> PageRoute | Sequence[PageRoute]

__iter__ 

__iter__() -> Iterator[PageRoute]

__len__ 

__len__() -> int

get 

get(key: str) -> PageRoute

keys 

keys() -> tuple[str, ...]

PageRoute dataclass 

PageRoute(key: str, label: str, purpose: str)

Navigation identity for one operator page.

key instance-attribute 

key: str

label instance-attribute 

label: str

purpose instance-attribute 

purpose: str

PageSurfacePort

Bases: Protocol

Workbench surface methods consumer pages may call.

refresh_view 

refresh_view(page_key: str, view: SurfaceView) -> None

show_detail 

show_detail(page_key: str, detail: DetailView) -> None

show_navigation 

show_navigation(
    page_key: str, navigation: PageNavigation
) -> None

show_view 

show_view(page_key: str, view: SurfaceView) -> None

SelectionAwareOperatorPage

Bases: Protocol

Optional hook for pages that consume workbench-owned selection tables.

selection_changed 

selection_changed(
    row_key: str,
    selected_keys: tuple[str, ...],
    context: PageContext,
) -> None