glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/cli/slash/tui/keybind_registry.py

@@ -0,0 +1,235 @@
+"""Keybinding registry helpers for TUI applications."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+DEFAULT_LEADER = "ctrl+x"
+_LEADER_TOKEN = "<leader>"
+
+_MODIFIER_ORDER = ("ctrl", "alt", "shift", "meta")
+_MODIFIER_SYNONYMS = {
+    "control": "ctrl",
+    "ctl": "ctrl",
+    "cmd": "meta",
+    "command": "meta",
+    "option": "alt",
+    "return": "enter",
+}
+
+_KEY_SYNONYMS = {
+    "esc": "escape",
+}
+
+_KEY_DISPLAY = {
+    "escape": "Esc",
+    "enter": "Enter",
+    "space": "Space",
+    "tab": "Tab",
+    "backspace": "Backspace",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Keybind:
+    """A registered keybinding."""
+
+    action: str
+    sequence: tuple[str, ...]
+    description: str
+    category: str | None = None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the keybind."""
+        return (
+            f"Keybind(action={self.action!r}, sequence={self.sequence}, "
+            f"description={self.description!r}, category={self.category!r})"
+        )
+
+
+class KeybindRegistry:
+    """Central registry of keybindings and associated metadata."""
+
+    def __init__(self, *, leader: str = DEFAULT_LEADER) -> None:
+        """Initialize the registry."""
+        normalized = _normalize_chord(leader)
+        self._leader = normalized or DEFAULT_LEADER
+        self._keybinds: dict[str, Keybind] = {}
+
+    @property
+    def leader(self) -> str:
+        """Return the normalized leader chord."""
+        return self._leader
+
+    def register(
+        self,
+        *,
+        action: str,
+        key: str,
+        description: str,
+        category: str | None = None,
+    ) -> Keybind:
+        """Register a keybinding for an action."""
+        if action in self._keybinds:
+            raise ValueError(f"Action already registered: {action}")
+
+        sequence = parse_key_sequence(key)
+        keybind = Keybind(action=action, sequence=sequence, description=description, category=category)
+        self._keybinds[action] = keybind
+        return keybind
+
+    def get(self, action: str) -> Keybind | None:
+        """Return keybind for action, if present."""
+        return self._keybinds.get(action)
+
+    def actions(self) -> list[str]:
+        """Return sorted list of registered actions."""
+        return sorted(self._keybinds)
+
+    def matches(self, action: str, sequence: str | Iterable[str]) -> bool:
+        """Return True if the provided sequence matches the action's keybind."""
+        keybind = self._keybinds.get(action)
+        if keybind is None:
+            return False
+
+        candidate = _coerce_sequence(sequence)
+        return candidate == keybind.sequence
+
+    def format(self, action: str) -> str:
+        """Return a human-readable sequence for an action."""
+        keybind = self._keybinds.get(action)
+        if keybind is None:
+            return ""
+
+        return format_key_sequence(keybind.sequence, leader=self._leader)
+
+
+def parse_key_sequence(key: str) -> tuple[str, ...]:
+    """Parse a key sequence string into normalized tokens."""
+    tokens = [token for token in key.strip().split() if token]
+    normalized: list[str] = []
+
+    for token in tokens:
+        if token.lower() == _LEADER_TOKEN:
+            normalized.append(_LEADER_TOKEN)
+            continue
+
+        chord = _normalize_chord(token)
+        if chord:
+            normalized.append(chord)
+
+    return tuple(normalized)
+
+
+def format_key_sequence(sequence: tuple[str, ...], *, leader: str = DEFAULT_LEADER) -> str:
+    """Format a normalized sequence into a display string."""
+    rendered: list[str] = []
+
+    for token in sequence:
+        if token == _LEADER_TOKEN:
+            rendered.append(_format_token(leader))
+            continue
+        rendered.append(_format_token(token))
+
+    return " ".join(rendered)
+
+
+def _coerce_sequence(sequence: str | Iterable[str]) -> tuple[str, ...]:
+    if isinstance(sequence, str):
+        return parse_key_sequence(sequence)
+
+    tokens: list[str] = []
+    for token in sequence:
+        if not token:
+            continue
+        if token.lower() == _LEADER_TOKEN:
+            tokens.append(_LEADER_TOKEN)
+            continue
+        chord = _normalize_chord(token)
+        if chord:
+            tokens.append(chord)
+
+    return tuple(tokens)
+
+
+def _normalize_chord(chord: str) -> str:
+    """Normalize a key chord string to canonical form.
+
+    Normalization rules:
+    - Converts separators: both '-' and '+' are normalized to '+'
+    - Handles synonyms: 'control'/'ctl' -> 'ctrl', 'cmd'/'command' -> 'meta', 'option' -> 'alt'
+    - Deduplicates modifiers: 'ctrl+ctrl+l' -> 'ctrl+l'
+    - Orders modifiers: ctrl < alt < shift < meta (unknown modifiers sort last)
+    - Case-insensitive: 'Ctrl+L' == 'ctrl+l' == 'CTRL-L'
+
+    Args:
+        chord: Key chord string (e.g., "Ctrl+L", "ctrl-l", "CTRL+CTRL+L")
+
+    Returns:
+        Normalized chord string (e.g., "ctrl+l") or empty string if invalid.
+    """
+    parts = [part for part in chord.replace("-", "+").split("+") if part.strip()]
+    if not parts:
+        return ""
+
+    normalized_parts = [_normalize_key_part(part) for part in parts]
+    if len(normalized_parts) == 1:
+        return normalized_parts[0]
+
+    modifiers, key = normalized_parts[:-1], normalized_parts[-1]
+
+    seen: set[str] = set()
+    unique_mods: list[str] = []
+    for mod in modifiers:
+        if mod in seen:
+            continue
+        seen.add(mod)
+        unique_mods.append(mod)
+
+    unique_mods.sort(key=_modifier_sort_key)
+    return "+".join([*unique_mods, key])
+
+
+def _normalize_key_part(part: str) -> str:
+    token = part.strip().lower()
+    token = _MODIFIER_SYNONYMS.get(token, token)
+    return _KEY_SYNONYMS.get(token, token)
+
+
+def _modifier_sort_key(modifier: str) -> int:
+    try:
+        return _MODIFIER_ORDER.index(modifier)
+    except ValueError:
+        return len(_MODIFIER_ORDER)
+
+
+def _format_token(token: str) -> str:
+    if "+" in token:
+        return _format_chord(token)
+
+    return _KEY_DISPLAY.get(token, token)
+
+
+def _format_chord(chord: str) -> str:
+    parts = chord.split("+")
+    modifiers, key = parts[:-1], parts[-1]
+
+    rendered_mods: list[str] = []
+    for mod in modifiers:
+        if mod == "ctrl":
+            rendered_mods.append("Ctrl")
+        elif mod == "alt":
+            rendered_mods.append("Alt")
+        elif mod == "shift":
+            rendered_mods.append("Shift")
+        elif mod == "meta":
+            rendered_mods.append("Meta")
+        else:
+            rendered_mods.append(mod.title())
+
+    rendered_key = _KEY_DISPLAY.get(key, key)
+    if len(rendered_key) == 1 and rendered_key.isalpha():
+        rendered_key = rendered_key.upper()
+
+    return "+".join([*rendered_mods, rendered_key])

glaip_sdk/cli/slash/tui/layouts/__init__.py

@@ -0,0 +1,14 @@
+"""Layout components for TUI applications.
+
+This package provides reusable layout components following the Harlequin pattern
+for multi-pane data-rich screens.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - optional dependency
+    from glaip_sdk.cli.slash.tui.layouts.harlequin import HarlequinScreen
+except Exception:  # pragma: no cover - optional dependency
+    HarlequinScreen = None  # type: ignore[assignment, misc]
+
+__all__ = ["HarlequinScreen"]

glaip_sdk/cli/slash/tui/layouts/harlequin.py

@@ -0,0 +1,184 @@
+"""Harlequin layout base class for multi-pane TUI screens.
+
+This module provides the HarlequinScreen base class, which implements a modern
+multi-pane "Harlequin" layout pattern for data-rich TUI screens. The layout uses
+a 25/75 split with a list on the left and detail content on the right.
+
+The Harlequin pattern is inspired by the Harlequin SQL client and provides:
+- Left Pane (25%): ListView or compact table for item selection
+- Right Pane (75%): Detail dashboard showing all fields, status, and action buttons
+- Black background (#000000) that overrides terminal transparency
+- Primary Blue borders (#005CB8)
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+try:  # pragma: no cover - optional dependency
+    from textual.screen import Screen
+    from textual.widget import Widget
+except Exception:  # pragma: no cover - optional dependency
+
+    class Screen:  # type: ignore[no-redef]
+        """Fallback Screen stub when Textual is unavailable."""
+
+        def __class_getitem__(cls, _):
+            """Return the class for typing subscripts."""
+            return cls
+
+    Widget = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    from glaip_sdk.cli.slash.tui.context import TUIContext
+
+try:  # pragma: no cover - optional dependency
+    from glaip_sdk.cli.slash.tui.toast import Toast, ToastContainer
+except Exception:  # pragma: no cover - optional dependency
+    Toast = None  # type: ignore[assignment, misc]
+    ToastContainer = None  # type: ignore[assignment, misc]
+
+# GDP Labs Brand Palette
+PRIMARY_BLUE = "#005CB8"
+BLACK_BACKGROUND = "#000000"
+
+
+if Widget is not None:
+
+    class HarlequinContainer(Widget):
+        """Base container for the Harlequin layout."""
+
+        DEFAULT_CSS = """
+        HarlequinContainer {
+            layout: horizontal;
+        }
+        """
+
+    class HarlequinPane(Widget):
+        """Pane container for Harlequin layout sections."""
+
+        DEFAULT_CSS = """
+        HarlequinPane {
+            layout: vertical;
+        }
+        """
+
+else:
+    HarlequinContainer = None  # type: ignore[assignment, misc]
+    HarlequinPane = None  # type: ignore[assignment, misc]
+
+
+class HarlequinScreen(Screen[None]):  # type: ignore[misc]
+    """Base class for Harlequin-style multi-pane screens.
+
+    This screen provides a 25/75 split layout with a left pane for navigation
+    and a right pane for details. The layout uses a black background that
+    overrides terminal transparency and primary blue borders.
+
+    Subclasses should override `compose()` to add their specific widgets to
+    the left and right panes. Use the container IDs "left-pane" and "right-pane"
+    to target specific panes in CSS or when querying widgets.
+
+    Example:
+        ```python
+        class AccountHarlequinScreen(HarlequinScreen):
+            def compose(self) -> ComposeResult:
+                yield from super().compose()
+                # Add widgets to left and right panes
+                self.query_one("#left-pane").mount(AccountListView())
+                self.query_one("#right-pane").mount(AccountDetailView())
+        ```
+
+    CSS:
+        The screen includes default styling for the Harlequin layout:
+        - Black background (#000000) for the entire screen
+        - Primary blue borders (#005CB8) for panes
+        - 25% width for left pane, 75% width for right pane
+    """
+
+    CSS = """
+    HarlequinScreen {
+        background: #000000;
+        layers: base toasts;
+    }
+
+    #harlequin-container {
+        width: 100%;
+        height: 100%;
+    }
+
+    #left-pane {
+        width: 25%;
+        border: solid #005CB8;
+        background: #000000;
+    }
+
+    #right-pane {
+        width: 75%;
+        border: solid #005CB8;
+        background: #000000;
+    }
+
+    #toast-container {
+        width: 100%;
+        height: auto;
+        dock: top;
+        align: right top;
+        layer: toasts;
+    }
+    """
+
+    def __init__(
+        self,
+        *,
+        ctx: TUIContext | None = None,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+    ) -> None:
+        """Initialize the Harlequin screen.
+
+        Args:
+            ctx: Optional TUI context for accessing services (keybinds, theme, toasts, clipboard).
+            name: Optional name for the screen.
+            id: Optional ID for the screen.
+            classes: Optional CSS classes for the screen.
+        """
+        super().__init__(name=name, id=id, classes=classes)
+        self._ctx: TUIContext | None = ctx
+
+    def compose(self) -> Any:
+        """Compose the Harlequin layout with left and right panes.
+
+        This method creates the base 25/75 split layout. Subclasses should
+        call `super().compose()` and then add their specific widgets to the
+        left and right panes.
+
+        Returns:
+            ComposeResult yielding the base layout containers.
+        """
+        if HarlequinContainer is None or HarlequinPane is None:
+            return
+
+        # Main container with horizontal split (25/75)
+        yield HarlequinContainer(
+            HarlequinPane(id="left-pane"),
+            HarlequinPane(id="right-pane"),
+            id="harlequin-container",
+        )
+
+        # Toast container for notifications
+        if Toast is not None and ToastContainer is not None:
+            yield ToastContainer(Toast(), id="toast-container")
+
+    @property
+    def ctx(self) -> TUIContext | None:
+        """Get the TUI context if available.
+
+        Returns:
+            TUIContext instance or None if not provided.
+        """
+        return self._ctx

glaip_sdk/cli/slash/tui/loading.py

@@ -0,0 +1,80 @@
+"""Shared helpers for toggling Textual loading indicators.
+
+This module provides unified helpers for showing/hiding both the built-in
+Textual LoadingIndicator and the custom PulseIndicator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from textual.widgets import LoadingIndicator
+
+from glaip_sdk.cli.slash.tui.indicators import PulseIndicator
+
+
+def _set_indicator_display(app: Any, selector: str, visible: bool) -> None:
+    try:
+        indicator = app.query_one(selector, PulseIndicator)
+        if visible:
+            indicator.display = True
+            indicator.start()
+        else:
+            indicator.stop()
+            indicator.display = False
+        return
+    except Exception:
+        pass
+
+    try:
+        indicator = app.query_one(selector, LoadingIndicator)
+        indicator.display = visible
+    except Exception:
+        return
+
+
+def show_loading_indicator(
+    app: Any,
+    selector: str,
+    *,
+    message: str | None = None,
+    set_status: Callable[..., None] | None = None,
+    status_style: str = "cyan",
+) -> None:
+    """Show a loading indicator (PulseIndicator or LoadingIndicator) and optionally set a status message.
+
+    Args:
+        app: Textual app instance containing the indicator widget
+        selector: CSS selector for the indicator widget
+        message: Optional message to display in the indicator
+        set_status: Optional callback to set status message (for fallback display)
+        status_style: Style for status message if set_status is provided
+    """
+    _set_indicator_display(app, selector, True)
+
+    try:
+        indicator = app.query_one(selector, PulseIndicator)
+        if message:
+            indicator.update_message(message)
+    except Exception:
+        pass
+
+    if message and set_status:
+        try:
+            set_status(message, status_style)
+        except TypeError:
+            try:
+                set_status(message)
+            except Exception:
+                return
+
+
+def hide_loading_indicator(app: Any, selector: str) -> None:
+    """Hide a loading indicator (PulseIndicator or LoadingIndicator).
+
+    Args:
+        app: Textual app instance containing the indicator widget
+        selector: CSS selector for the indicator widget
+    """
+    _set_indicator_display(app, selector, False)