groundskeeping 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: groundskeeping
-Version: 0.2.2
+Version: 0.3.0
 Summary: Reusable Textual operator shell, workbench, configuration browser, and telemetry primitives.
 Author: UNSW CAVA platform tooling
 Requires-Python: >=3.12

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

@@ -20,8 +20,9 @@ Use `SectionNavigation` for peer areas such as Database, Embeddings, and Runtime
 evaluation run with nested artefacts.
 
 Translate domain objects before they reach the workbench. The workbench understands
-`SectionItem`, `CatalogueItem`, `TableView`, `TreeView`, and friends; it does not need to know
-what a Groundworkers resource or `cava-nlp-shard` evaluation object is.
+`SectionItem`, `CatalogueItem`, `TableView`, `SelectionTableView`, `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
@@ -54,6 +55,12 @@ startup rather than when an operator clicks a tab.
 Row events return to the active page. The workbench renders generic models; the page decides
 what a highlighted row means.
 
+Use `SelectionTableView` when rows are controls, not just data. It renders a
+Groundskeeping-owned selection list with stable row keys, disabled row handling, and
+selection modes for single, multiple, or all-vs-specific selection. Pages that need the full
+selected-key state can implement the optional `SelectionAwareOperatorPage.selection_changed`
+hook; older pages still receive `row_selected` for compatibility.
+
 Detail panes can render `TextView`, `KeyValueView`, or `TableView`. Use a detail `TableView`
 when the selected item has its own repeated data, such as available LLM models for a provider.
 

{groundskeeping-0.2.2 → groundskeeping-0.3.0}/docs/wizards.md

@@ -64,6 +64,10 @@ The contracts cover three step types:
 secret, and multiline fields. It also carries presentation metadata such as placeholder text,
 help text, disabled/read-only state, and secret behaviour.
 
+Choice fields render as Textual `Select` controls. Keyboard and mouse selection both populate
+the submitted field value, and long option lists open as scrollable menus while focus stays
+with the active control.
+
 ## Secrets and revisions
 
 Real candidate values belong in the controller. Snapshots should carry only values needed to

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

@@ -227,6 +227,19 @@ class OperatorApp(App[None]):
                 str(event.row_key.value), self._page_context
             )
 
+    def on_workbench_selection_highlighted(
+        self, event: Workbench.SelectionHighlighted
+    ) -> None:
+        self._active_widget().row_highlighted(event.row_key, self._page_context)
+
+    def on_workbench_selection_changed(self, event: Workbench.SelectionChanged) -> None:
+        page = self._active_widget()
+        handler = getattr(page, "selection_changed", None)
+        if callable(handler):
+            handler(event.row_key, event.selected_keys, self._page_context)
+            return
+        page.row_selected(event.row_key, self._page_context)
+
     def on_button_pressed(self, event: Button.Pressed) -> None:
         action_key = self._workbench.action_key(event.button.id)
         if action_key is not None:

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

@@ -40,6 +40,7 @@ from groundskeeping.contracts.pages import (
     PageRegistry,
     PageRoute,
     PageSurfacePort,
+    SelectionAwareOperatorPage,
 )
 from groundskeeping.contracts.telemetry import (
     MetricValue,
@@ -60,6 +61,9 @@ from groundskeeping.contracts.views import (
     PageNavigation,
     SectionItem,
     SectionNavigation,
+    SelectionMode,
+    SelectionTableRow,
+    SelectionTableView,
     SemanticStatus,
     SurfaceView,
     TableRow,

{groundskeeping-0.2.2 → groundskeeping-0.3.0}/src/groundskeeping/contracts/pages.py

@@ -114,6 +114,14 @@ class OperatorPage(Protocol):
     def row_selected(self, row_key: str, context: PageContext) -> None: ...
 
 
+class SelectionAwareOperatorPage(Protocol):
+    """Optional hook for pages that consume workbench-owned selection tables."""
+
+    def selection_changed(
+        self, row_key: str, selected_keys: tuple[str, ...], context: PageContext
+    ) -> None: ...
+
+
 @dataclass(frozen=True)
 class PageRegistration:
     """A page route plus the factory that creates the page widget."""

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

@@ -8,6 +8,7 @@ from enum import StrEnum
 from typing import Literal
 
 type ViewActionVariant = Literal["default", "primary", "success", "warning", "error"]
+type SelectionMode = Literal["single", "multiple", "all_or_specific"]
 
 MAX_VIEW_ACTIONS = 6
 
@@ -115,6 +116,32 @@ class TableView:
     actions: tuple[ViewAction, ...] = ()
 
 
+@dataclass(frozen=True)
+class SelectionTableRow:
+    """One selectable row in a workbench-owned selection table."""
+
+    key: str
+    cells: tuple[str, ...]
+    selected: bool = False
+    disabled: bool = False
+    selection_group: str | None = None
+    detail: object | None = None
+
+
+@dataclass(frozen=True)
+class SelectionTableView:
+    """A table-shaped surface where Groundskeeping owns row toggle semantics."""
+
+    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
+
+
 @dataclass(frozen=True)
 class TreeNode:
     """A tree-shaped detail node."""
@@ -176,4 +203,4 @@ class KeyValueView:
 
 
 type DetailView = TextView | KeyValueView | TableView
-type SurfaceView = TableView | TreeView | EmptyView | LoadingView
+type SurfaceView = TableView | SelectionTableView | TreeView | EmptyView | LoadingView

{groundskeeping-0.2.2 → groundskeeping-0.3.0}/src/groundskeeping/demo.py

@@ -32,6 +32,8 @@ from groundskeeping.contracts import (
     ReviewStep,
     SectionItem,
     SectionNavigation,
+    SelectionTableRow,
+    SelectionTableView,
     SemanticStatus,
     SurfaceView,
     TableRow,
@@ -116,12 +118,22 @@ TELEMETRY_ROUTE = PageRoute(
 class OverviewPage(_DemoPage):
     route = OVERVIEW_ROUTE
 
+    def __init__(self) -> None:
+        super().__init__()
+        self._selected_vocab_keys: tuple[str, ...] = ("__all__",)
+
     def build_navigation(self, context: PageContext) -> SectionNavigation:
         return SectionNavigation(
             items=(
                 SectionItem(
                     "overview.shell", "Shell contracts", status=SemanticStatus.OK
                 ),
+                SectionItem(
+                    "overview.selection",
+                    "Selection table",
+                    status=SemanticStatus.RUNNING,
+                    description="All-vs-specific row controls",
+                ),
                 SectionItem("overview.boundaries", "Consumer boundaries"),
             )
         )
@@ -144,6 +156,71 @@ class OverviewPage(_DemoPage):
             ),
         )
 
+    def navigation_selected(self, item: NavigationItem, context: PageContext) -> None:
+        if item.key == "overview.selection":
+            context.surface.show_view(self.route.key, self._selection_view())
+            context.surface.show_detail(
+                self.route.key,
+                KeyValueView(
+                    title="Selection",
+                    rows=(
+                        ("changed row", "-"),
+                        ("selected keys", ", ".join(self._selected_vocab_keys)),
+                    ),
+                ),
+            )
+            return
+        context.surface.show_view(self.route.key, self.landing_view(context))
+
+    def selection_changed(
+        self, row_key: str, selected_keys: tuple[str, ...], context: PageContext
+    ) -> None:
+        self._selected_vocab_keys = selected_keys or ("__all__",)
+        context.surface.show_view(self.route.key, self._selection_view())
+        context.surface.show_detail(
+            self.route.key,
+            KeyValueView(
+                title="Selection",
+                rows=(
+                    ("changed row", row_key),
+                    ("selected keys", ", ".join(self._selected_vocab_keys)),
+                ),
+            ),
+        )
+
+    def _selection_view(self) -> SelectionTableView:
+        selected = set(self._selected_vocab_keys)
+        return SelectionTableView(
+            title="Vocabulary selection",
+            message="workbench-owned all-vs-specific controls",
+            status=SemanticStatus.RUNNING,
+            columns=("Vocabulary", "Coverage", "State"),
+            selection_mode="all_or_specific",
+            all_row_key="__all__",
+            rows=(
+                SelectionTableRow(
+                    "__all__",
+                    ("All vocabularies", "default", "ready"),
+                    selected="__all__" in selected,
+                ),
+                SelectionTableRow(
+                    "snomed",
+                    ("SNOMED CT", "100%", "complete"),
+                    disabled=True,
+                ),
+                SelectionTableRow(
+                    "loinc",
+                    ("LOINC", "73%", "available"),
+                    selected="loinc" in selected,
+                ),
+                SelectionTableRow(
+                    "rxnorm",
+                    ("RxNorm", "41%", "available"),
+                    selected="rxnorm" in selected,
+                ),
+            ),
+        )
+
 
 class ConfigPage(_DemoPage):
     route = CONFIG_ROUTE

{groundskeeping-0.2.2 → groundskeeping-0.3.0}/src/groundskeeping/themes/groundskeeping.tcss

@@ -102,6 +102,15 @@ Screen {
     color: $text-warning;
 }
 
+Select.wizard-choice-list {
+    width: 1fr;
+}
+
+Select.wizard-choice-list > SelectOverlay {
+    height: 10;
+    max-height: 10;
+}
+
 .section {
     border: round $accent 40%;
     border-title-align: left;

{groundskeeping-0.2.2 → groundskeeping-0.3.0}/src/groundskeeping/widgets/wizard.py

@@ -14,12 +14,10 @@ from textual.widgets import (
     DataTable,
     Input,
     Label,
-    OptionList,
     Select,
     Static,
     TextArea,
 )
-from textual.widgets.option_list import Option
 
 from groundskeeping.contracts.actions import FieldKind, FieldSpec
 from groundskeeping.contracts.wizards import (
@@ -45,6 +43,7 @@ class WizardScreen(ModalScreen[WizardResult]):
         self._field_by_widget_id: dict[str, FieldSpec] = {}
         self._choice_widget_id = "wizard-choice"
         self._blank_choice_id = "__groundskeeping_blank_choice__"
+        self._no_choice_id = "__groundskeeping_no_choice__"
 
     def compose(self) -> ComposeResult:
         with Vertical(id="wizard-frame"):
@@ -116,7 +115,9 @@ class WizardScreen(ModalScreen[WizardResult]):
                 widget_id = f"wizard-field-{index}"
                 self._field_by_widget_id[widget_id] = field
                 await body.mount(Label(field.label, classes="wizard-field-label"))
-                await body.mount(self._field_widget(widget_id, field, snapshot.values.get(field.key)))
+                await body.mount(
+                    self._field_widget(widget_id, field, snapshot.values.get(field.key))
+                )
                 if field.help:
                     await body.mount(Static(field.help, classes="wizard-field-help"))
             return
@@ -130,11 +131,15 @@ class WizardScreen(ModalScreen[WizardResult]):
                     value=current if current is not None else Select.BLANK,
                     id=self._choice_widget_id,
                     allow_blank=False,
+                    classes="wizard-choice-list",
                 )
             )
             for choice in step.choices:
                 await body.mount(
-                    Static(f"{choice.label}: {choice.description}", classes="wizard-field-help")
+                    Static(
+                        f"{choice.label}: {choice.description}",
+                        classes="wizard-field-help",
+                    )
                 )
             return
         if isinstance(step, ReviewStep):
@@ -154,43 +159,50 @@ class WizardScreen(ModalScreen[WizardResult]):
 
     def _field_widget(
         self, widget_id: str, field: FieldSpec, value: object
-    ) -> Input | TextArea | Checkbox | OptionList:
+    ) -> Input | TextArea | Checkbox | Select[str]:
         disabled = field.disabled or field.read_only
         if field.kind is FieldKind.BOOLEAN:
-            return Checkbox(value=bool(value if value is not None else field.default), id=widget_id, disabled=disabled)
+            return Checkbox(
+                value=bool(value if value is not None else field.default),
+                id=widget_id,
+                disabled=disabled,
+            )
         if field.kind is FieldKind.CHOICE:
             current = value if value is not None else field.default
-            options = []
+            options: list[tuple[str, str]] = []
             if not field.required:
                 options.append(
-                    Option(field.placeholder or "No selection", id=self._blank_choice_id)
+                    (field.placeholder or "No selection", self._blank_choice_id)
                 )
             options.extend(
-                Option(
+                (
                     choice.label
                     if choice.description is None
                     else f"{choice.label} — {choice.description}",
-                    id=choice.value,
+                    choice.value,
                 )
                 for choice in field.choices
             )
             if not options:
-                options.append(Option(field.placeholder or "No choices", disabled=True))
-            widget = OptionList(
-                *options,
+                options.append((field.placeholder or "No choices", self._no_choice_id))
+            option_values = tuple(option_value for _, option_value in options)
+            if current in option_values:
+                selected = str(current)
+            elif not field.required:
+                selected = self._blank_choice_id
+            elif field.choices:
+                selected = field.choices[0].value
+            else:
+                selected = self._no_choice_id
+            return Select(
+                options,
+                prompt=field.placeholder or "Choose an option",
+                value=selected,
+                allow_blank=False,
                 id=widget_id,
-                disabled=disabled,
+                disabled=disabled or not field.choices,
                 classes="wizard-choice-list",
             )
-            widget.styles.height = min(max(len(options), 2), 8)
-            choice_ids = tuple(option.id for option in options)
-            if current is None and not field.required:
-                widget.highlighted = 0
-            elif current in choice_ids:
-                widget.highlighted = choice_ids.index(current)
-            elif field.required and field.choices:
-                widget.highlighted = 0
-            return widget
         if field.kind is FieldKind.MULTILINE:
             widget = TextArea("" if value is None else str(value), id=widget_id)
             widget.read_only = disabled
@@ -265,14 +277,15 @@ def _widget_value(widget: object) -> object:
         return widget.text
     if isinstance(widget, Checkbox):
         return widget.value
-    if isinstance(widget, OptionList):
-        if widget.highlighted is None:
-            return None
-        selected = widget.get_option_at_index(widget.highlighted)
-        return None if selected.id == "__groundskeeping_blank_choice__" else selected.id
     if isinstance(widget, Select):
         selected = widget.value
-        return None if selected is Select.BLANK else selected
+        if selected in {
+            Select.BLANK,
+            "__groundskeeping_blank_choice__",
+            "__groundskeeping_no_choice__",
+        }:
+            return None
+        return selected
     return None