groundskeeping 0.2.1__tar.gz → 0.2.2__tar.gz

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groundskeeping
-Version: 0.2.1
+Version: 0.2.2
 Summary: Reusable Textual operator shell, workbench, configuration browser, and telemetry primitives.
 Author: UNSW CAVA platform tooling
 Requires-Python: >=3.12
@@ -75,6 +75,9 @@ OperatorApp(spec).run()
 
 Groundskeeping owns the frame around those pages. `DatabaseSetupPage`,
 `EmbeddingsSetupPage`, and the services behind them stay in the application.
+Use `workbench_labels` on `OperatorAppSpec` when the shared pane chrome needs different
+language, such as naming the upper-right pane **Checks** instead of **Rows**. Page navigation
+and view contracts still supply their own content titles.
 
 The default page surface is the workbench:
 

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/README.md

@@ -58,6 +58,9 @@ OperatorApp(spec).run()
 
 Groundskeeping owns the frame around those pages. `DatabaseSetupPage`,
 `EmbeddingsSetupPage`, and the services behind them stay in the application.
+Use `workbench_labels` on `OperatorAppSpec` when the shared pane chrome needs different
+language, such as naming the upper-right pane **Checks** instead of **Rows**. Page navigation
+and view contracts still supply their own content titles.
 
 The default page surface is the workbench:
 

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/docs/pages.md

@@ -23,6 +23,11 @@ Translate domain objects before they reach the workbench. The workbench understa
 `SectionItem`, `CatalogueItem`, `TableView`, `TreeView`, and friends; it does not need to know
 what a Groundworkers resource or `cava-nlp-shard` evaluation object is.
 
+Use `OperatorAppSpec.workbench_labels` to rename shared pane chrome such as the result and
+detail panel labels. Page-owned titles still live on navigation and view contracts: for
+example, `SectionNavigation.title` names the left pane for a specific page, and
+`TableView.title` names the current result content.
+
 ## Routing
 
 `PageRoute` is the navigation identity for one page: a `key`, an operator-facing `label`, and

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/src/groundskeeping/app.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import ClassVar
+from typing import ClassVar, cast
 
 from rich.text import Text
 from textual.app import App, ComposeResult
@@ -52,6 +52,7 @@ from groundskeeping.contracts.views import (
     PageNavigation,
     SectionItem,
     SurfaceView,
+    WorkbenchLabels,
 )
 from groundskeeping.contracts.wizards import (
     WizardController,
@@ -76,6 +77,7 @@ class OperatorAppSpec:
     operation_policy: OperationPolicy = field(default_factory=AllowAllOperationPolicy)
     job_policy: JobPolicy = field(default_factory=SingleForegroundJobPolicy)
     result_presenter: ResultPresenter = field(default_factory=DefaultResultPresenter)
+    workbench_labels: WorkbenchLabels = field(default_factory=WorkbenchLabels)
     default_page: str | None = None
     metadata: Mapping[str, object] | None = None
 
@@ -157,7 +159,7 @@ class OperatorApp(App[None]):
         self.sub_title = spec.subtitle or ""
         self.jobs = JobManager(spec.job_policy)
         self._active_page = spec.default_page or self.registry[0].key
-        self._workbench = Workbench()
+        self._workbench = Workbench(spec.workbench_labels)
         self._surface = _WorkbenchSurface(self._workbench)
         # Textual's App already owns an internal `_context()` method used during
         # startup. Keep the page-facing context under a distinct name so the shell does
@@ -180,13 +182,11 @@ class OperatorApp(App[None]):
             with Vertical(id="workspace"):
                 yield Label("", id="workspace-title")
                 for route in self.registry:
-                    page = self._pages[route.key]
-                    if not isinstance(page, Widget):
-                        raise TypeError(f"Page {route.key!r} must be a Textual Widget.")
-                    page.add_class("operator-page")
-                    page.styles.height = 0
-                    page.styles.max_height = 0
-                    yield page
+                    page_widget = self._page_widget(route.key)
+                    page_widget.add_class("operator-page")
+                    page_widget.styles.height = 0
+                    page_widget.styles.max_height = 0
+                    yield page_widget
                 yield self._workbench
         yield Footer()
 
@@ -254,16 +254,13 @@ class OperatorApp(App[None]):
         next_page = self._pages[page_key]
         if previous is not None and previous is not next_page:
             previous.deactivate(self._page_context)
-            if isinstance(previous, Widget):
-                previous.remove_class("-active")
+            self._page_widget(self._active_page).remove_class("-active")
         self._active_page = page_key
-        page = next_page
-        if isinstance(page, Widget):
-            page.add_class("-active")
+        self._page_widget(page_key).add_class("-active")
         tabs = self.query_one("#page-tabs", Tabs)
         if tabs.active != page_key:
             tabs.active = page_key
-        page.activate(self._page_context)
+        next_page.activate(self._page_context)
         self._render_page(route)
 
     def _render_page(self, route: PageRoute) -> None:
@@ -286,6 +283,12 @@ class OperatorApp(App[None]):
     def _active_widget(self) -> OperatorPage:
         return self._pages[self._active_page]
 
+    def _page_widget(self, page_key: str) -> Widget:
+        page = self._pages[page_key]
+        if not isinstance(page, Widget):
+            raise TypeError(f"Page {page_key!r} must be a Textual Widget.")
+        return cast(Widget, page)
+
     def _select_navigation_item(self, item: NavigationItem) -> None:
         self._active_widget().navigation_selected(item, self._page_context)
 

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/src/groundskeeping/contracts/__init__.py

@@ -69,6 +69,7 @@ from groundskeeping.contracts.views import (
     TreeView,
     ViewAction,
     ViewActionVariant,
+    WorkbenchLabels,
 )
 from groundskeeping.contracts.wizards import (
     Choice,

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/src/groundskeeping/contracts/views.py

@@ -12,6 +12,21 @@ type ViewActionVariant = Literal["default", "primary", "success", "warning", "er
 MAX_VIEW_ACTIONS = 6
 
 
+@dataclass(frozen=True)
+class WorkbenchLabels:
+    """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.
+    """
+
+    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")
+
+
 class SemanticStatus(StrEnum):
     """Small health/status vocabulary understood by shared widgets."""
 

groundskeeping-0.2.2/src/groundskeeping/py.typed

@@ -0,0 +1 @@
+

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/src/groundskeeping/widgets/workbench.py

@@ -29,6 +29,7 @@ from groundskeeping.contracts.views import (
     TreeNode,
     TreeView,
     ViewAction,
+    WorkbenchLabels,
 )
 from groundskeeping.theme import node_label, status_style
 from groundskeeping.widgets.primitives import EmptyState, LoadingState
@@ -37,8 +38,9 @@ from groundskeeping.widgets.primitives import EmptyState, LoadingState
 class Workbench(Widget):
     """Shared page surface with navigation left and rows/detail right."""
 
-    def __init__(self) -> None:
+    def __init__(self, labels: WorkbenchLabels | None = None) -> None:
         super().__init__(id="workbench")
+        self.labels = labels or WorkbenchLabels()
         self._loading_timer: Timer | None = None
         self._loading_frame = 0
         self._loading_view: LoadingView | None = None
@@ -54,7 +56,7 @@ class Workbench(Widget):
                     with Horizontal(id="result-header"):
                         yield Static("", id="result-status")
                         yield Static(
-                            "Select a section to inspect it.", id="result-summary"
+                            self.labels.initial_result_summary, id="result-summary"
                         )
                     with Horizontal(id="result-actions"):
                         for index in range(MAX_VIEW_ACTIONS):
@@ -68,9 +70,9 @@ class Workbench(Widget):
                     yield DataTable(id="context-table")
 
     def on_mount(self) -> None:
-        self.query_one("#catalogue-panel").border_title = "Sections"
-        self.query_one("#result-panel").border_title = "Rows"
-        self.query_one("#context-panel").border_title = "Detail"
+        self.query_one("#catalogue-panel").border_title = self.labels.navigation_panel
+        self.query_one("#result-panel").border_title = self.labels.result_panel
+        self.query_one("#context-panel").border_title = self.labels.detail_panel
         self.catalogue.show_root = False
         self.catalogue.root.expand()
         self.catalogue.styles.display = "none"
@@ -317,12 +319,14 @@ class Workbench(Widget):
         self,
         rows: Iterable[tuple[str, str]],
         *,
-        columns: tuple[str, str] = ("Field", "Value"),
+        columns: tuple[str, ...] | None = None,
     ) -> None:
         self.query_one("#context", TextArea).styles.display = "none"
         table = self.query_one("#context-table", DataTable)
         table.styles.display = "block"
         table.clear(columns=True)
-        table.add_columns(*columns)
+        table.add_columns(
+            *(self.labels.key_value_columns if columns is None else columns)
+        )
         for label, value in rows:
             table.add_row(label, value)

{groundskeeping-0.2.1 → groundskeeping-0.2.2}/tests/test_app_smoke.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 from dataclasses import replace
 
+import pytest
 from textual.widget import Widget
 from textual.widgets import Button, DataTable
 
@@ -23,6 +24,7 @@ from groundskeeping.contracts import (
     ViewAction,
     WizardResult,
     WizardResultStatus,
+    WorkbenchLabels,
 )
 from groundskeeping.demo import build_demo_spec
 
@@ -64,6 +66,35 @@ class _CountingPage(Widget):
         return None
 
 
+class _NonWidgetPage:
+    def __init__(self, route: PageRoute) -> None:
+        self.route = route
+
+    def activate(self, context: PageContext) -> None:
+        return None
+
+    def deactivate(self, context: PageContext) -> None:
+        return None
+
+    def build_navigation(self, context: PageContext) -> SectionNavigation:
+        return SectionNavigation(items=())
+
+    def landing_view(self, context: PageContext) -> SurfaceView:
+        return EmptyView(title=self.route.label, message="render")
+
+    def navigation_selected(self, item: NavigationItem, context: PageContext) -> None:
+        return None
+
+    def action_selected(self, action_key: str, context: PageContext) -> None:
+        return None
+
+    def row_highlighted(self, row_key: str, context: PageContext) -> None:
+        return None
+
+    def row_selected(self, row_key: str, context: PageContext) -> None:
+        return None
+
+
 def test_demo_app_enters_textual_startup_context() -> None:
     async def run() -> None:
         app = OperatorApp(build_demo_spec())
@@ -95,6 +126,25 @@ def test_demo_app_enters_textual_startup_context() -> None:
     asyncio.run(run())
 
 
+def test_operator_app_rejects_non_widget_pages() -> None:
+    async def run() -> None:
+        route = PageRoute("setup", "Setup", "Setup page")
+        app = OperatorApp(
+            OperatorAppSpec(
+                app_id="non-widget-test",
+                title="Non Widget Test",
+                subtitle=None,
+                pages=(PageRegistration(route, lambda context: _NonWidgetPage(route)),),
+            )
+        )
+
+        with pytest.raises(TypeError, match="must be a Textual Widget"):
+            async with app.run_test():
+                pass
+
+    asyncio.run(run())
+
+
 def test_single_page_hides_tabs_without_removing_page_registry() -> None:
     async def run() -> None:
         demo = build_demo_spec()
@@ -113,6 +163,46 @@ def test_single_page_hides_tabs_without_removing_page_registry() -> None:
     asyncio.run(run())
 
 
+def test_app_spec_can_override_workbench_chrome_labels() -> None:
+    async def run() -> None:
+        demo = build_demo_spec()
+        spec = replace(
+            demo,
+            workbench_labels=WorkbenchLabels(
+                navigation_panel="Setup areas",
+                result_panel="Checks",
+                detail_panel="Inspector",
+                initial_result_summary="Choose a setup area.",
+                key_value_columns=("Setting", "Value"),
+            ),
+        )
+        app = OperatorApp(spec)
+
+        async with app.run_test() as pilot:
+            assert app.query_one("#result-panel").border_title == "Checks"
+            assert app.query_one("#context-panel").border_title == "Inspector"
+
+            app._workbench.show_navigation(SectionNavigation(items=()))
+            assert app.query_one("#catalogue-panel").border_title == "Sections"
+
+            app._workbench.show_context_table((("provider", "ollama"),))
+            await pilot.pause()
+
+            table = app.query_one("#context-table", DataTable)
+            assert tuple(str(column.label) for column in table.ordered_columns) == (
+                "Setting",
+                "Value",
+            )
+
+            app._workbench.show_context_table((), columns=())
+            await pilot.pause()
+
+            assert len(table.ordered_columns) == 0
+            await pilot.press("q")
+
+    asyncio.run(run())
+
+
 def test_wizard_result_refreshes_active_page_when_requested() -> None:
     async def run() -> None:
         active_route = PageRoute("setup", "Setup", "Setup page")