hatui-kit 0.1.0__py3-none-any.whl

hatui/__init__.py

@@ -0,0 +1,11 @@
+"""Hatui package."""
+
+__all__ = ["HatuiApp"]
+
+
+def __getattr__(name: str):
+    if name == "HatuiApp":
+        from hatui.app import HatuiApp
+
+        return HatuiApp
+    raise AttributeError(name)

hatui/__main__.py

@@ -0,0 +1,5 @@
+from hatui.app import main
+
+
+if __name__ == "__main__":
+    main()

hatui/app.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import sys
+from copy import deepcopy
+from pathlib import Path
+
+from hatui.runtime.bootstrap import build_runtime
+from hatui.runtime.cli import build_parser, normalize_argv, preferred_glyph_mode, resolve_spec_context, write_cli_text
+from hatui.runtime.defaults import create_provider_registry, create_widget_registry
+from hatui.runtime.engine import AppEngine
+from hatui.runtime.loader import ScreenSpecLoader
+from hatui.runtime.watcher import SpecWatcher
+
+
+class HatuiApp:
+    def __init__(
+        self,
+        spec_path: str | Path,
+        *,
+        widget_registry=None,
+        provider_registry=None,
+        watch: bool = False,
+        bundled_demo: bool = False,
+        glyph_mode: str = "unicode",
+    ):
+        self.spec_path = Path(spec_path)
+        self.is_bundled_demo = bundled_demo
+        self.glyph_mode = glyph_mode
+        self.widget_registry = widget_registry or create_widget_registry()
+        self.provider_registry = provider_registry or create_provider_registry()
+        self.loader = ScreenSpecLoader(self.widget_registry, self.provider_registry)
+        self.engine = AppEngine()
+        self.watcher = SpecWatcher(cli_watch=watch, allow_watch=not bundled_demo)
+        self.loaded_files: list[Path] = []
+        self._bootstrap_runtime()
+
+    @property
+    def screen_buffer(self):
+        return self.engine.screen_buffer
+
+    @property
+    def input_manager(self):
+        return self.engine.input_manager
+
+    @property
+    def environment(self):
+        return self.engine.environment
+
+    def _bootstrap_runtime(
+        self,
+        *,
+        preserved_state: dict | None = None,
+        preserved_stack: list[str] | None = None,
+        preserved_focus: str | None = None,
+        preserved_focus_map: dict[str, str] | None = None,
+    ) -> None:
+        runtime = build_runtime(
+            spec_path=self.spec_path,
+            loader=self.loader,
+            preserved_state=preserved_state,
+            preserved_stack=preserved_stack,
+            preserved_focus=preserved_focus,
+            preserved_focus_map=preserved_focus_map,
+            glyph_mode=self.glyph_mode,
+        )
+        self.store = runtime.store
+        self.router = runtime.router
+        self.root_widget = runtime.root_widget
+        self.provider_manager = runtime.provider_manager
+        self.loaded_files = runtime.loaded_files
+        self.watcher.configure(
+            spec_path=self.spec_path,
+            loaded_files=self.loaded_files,
+            dev_spec=runtime.dev_spec,
+        )
+
+    def debug_snapshot(self) -> dict[str, object]:
+        watch = self.watcher.snapshot()
+        return {
+            "watch_enabled": watch.enabled,
+            "watch_interval_s": watch.interval_s,
+            "watch_debounce_s": watch.debounce_s,
+            "watched_files": watch.watched_files,
+            "watched_file_count": len(watch.watched_files),
+            "pending_reload": watch.pending_reload,
+            "pending_changed_files": watch.pending_changed_files,
+            "reload_count": watch.reload_count,
+            "last_reload_at": watch.last_reload_at,
+            "last_reload_error": watch.last_reload_error,
+            **self.engine.stats.as_dict(),
+        }
+
+    def render_frame(self, *, width: int | None = None, height: int | None = None, flush: bool = False):
+        return self.engine.render_frame(self, width=width, height=height, flush=flush)
+
+    def preview(self, *, width: int = 100, height: int = 32, frames: int = 1, route: str | None = None) -> str:
+        if route:
+            self.root_widget.route_set(route, self.root_widget.context)
+        self.engine.activate_providers(self)
+        try:
+            for _ in range(max(frames, 1)):
+                self.render_frame(width=width, height=height, flush=False)
+            return self.screen_buffer.to_plain_text()
+        finally:
+            self.engine.deactivate_providers(self)
+
+    def reload(self) -> None:
+        previous_state = deepcopy(self.store.state)
+        previous_stack = list(self.router.stack)
+        previous_focus = self.root_widget.context.focused_widget
+        previous_focus_map = dict(self.root_widget.state.get("last_focused_by_route", {}))
+        old_store = self.store
+        old_router = self.router
+        old_root_widget = self.root_widget
+        old_provider_manager = self.provider_manager
+        old_loaded_files = list(self.loaded_files)
+        watcher_state = self.watcher.capture_state()
+        providers_active = self.engine.providers_active
+        self.engine.deactivate_providers(self)
+        try:
+            self._bootstrap_runtime(
+                preserved_state=previous_state,
+                preserved_stack=previous_stack,
+                preserved_focus=previous_focus,
+                preserved_focus_map=previous_focus_map,
+            )
+            if providers_active:
+                self.engine.activate_providers(self)
+            self.watcher.mark_reload_success(round(self.engine.elapsed_time, 3))
+        except Exception:
+            self.store = old_store
+            self.router = old_router
+            self.root_widget = old_root_widget
+            self.provider_manager = old_provider_manager
+            self.loaded_files = old_loaded_files
+            self.watcher.restore_state(watcher_state)
+            if providers_active:
+                self.engine.activate_providers(self)
+            raise
+
+    def run(self):
+        with self.environment.manage():
+            self.engine.activate_providers(self)
+            try:
+                while True:
+                    self.engine.dispatch_input(self)
+                    self.engine.resize_to_terminal()
+                    if self.watcher.should_reload():
+                        try:
+                            self.reload()
+                        except Exception as exc:
+                            self.watcher.mark_reload_error(str(exc))
+                    self.render_frame(flush=True)
+            except KeyboardInterrupt:
+                pass
+            finally:
+                self.engine.deactivate_providers(self)
+
+
+def main():
+    argv = normalize_argv()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    command = args.command or "run"
+    spec_arg = getattr(args, "spec", None)
+    spec_context, is_bundled_demo = resolve_spec_context(spec_arg)
+
+    with spec_context as spec_path:
+        if command == "validate":
+            loader = ScreenSpecLoader(create_widget_registry(), create_provider_registry())
+            messages = loader.validate_spec(spec_path)
+            errors = [message for message in messages if message.level == "error"]
+            if errors:
+                for message in errors:
+                    print(message.format(), file=sys.stderr)
+                raise SystemExit(1)
+            print(f"Valid Hatui spec: {spec_path}")
+            return
+
+        app = HatuiApp(
+            spec_path=spec_path,
+            watch=bool(getattr(args, "watch", False)),
+            bundled_demo=is_bundled_demo,
+            glyph_mode=preferred_glyph_mode(),
+        )
+        if command == "preview":
+            preview_text = app.preview(
+                width=max(args.width, 1),
+                height=max(args.height, 1),
+                frames=max(args.frames, 1),
+                route=args.route,
+            )
+            write_cli_text(preview_text)
+            return
+        app.run()
+
+
+if __name__ == "__main__":
+    main()

hatui/core/__init__.py

@@ -0,0 +1 @@
+"""Core module, containing base classes and utilities for the application."""

hatui/core/actions.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class KeyBinding:
+    key: str
+    modifiers: tuple[str, ...] = ()
+    action: str = ""
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def chord(self) -> str:
+        if not self.modifiers:
+            return self.key
+        return "+".join([*self.modifiers, self.key])
+
+
+def normalize_chord(key: str, modifiers: list[str] | tuple[str, ...] | None = None) -> str:
+    parts = [
+        part.strip().lower()
+        for part in (modifiers or [])
+        if part and part.strip().lower() != "arrow"
+    ]
+    key_name = key.strip().lower()
+    if key_name:
+        parts.append(key_name)
+    return "+".join(parts)
+
+
+def parse_keybinding(spec: str | dict[str, Any]) -> KeyBinding:
+    if isinstance(spec, str):
+        return KeyBinding(key=spec.strip().lower())
+
+    chord = str(spec.get("key", "")).strip().lower()
+    if not chord:
+        raise ValueError("Keybinding spec missing 'key'")
+
+    parts = [part for part in chord.split("+") if part]
+    key = parts[-1]
+    modifiers = tuple(parts[:-1])
+    action = str(spec.get("action", "")).strip()
+    payload = dict(spec.get("payload", {}) or {})
+    return KeyBinding(key=key, modifiers=modifiers, action=action, payload=payload)

hatui/core/context.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+@dataclass
+class Context:
+    """
+    A class to represent the context of the application.
+    """
+    name: str
+    version: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+    # Terminal properties
+    terminal_width: int = None
+    terminal_height:int = None
+    delta_time: float = 0.0
+    elapsed_time: float = 0.0
+    frame: int = 0
+    focused_widget: str | None = None
+    last_key: str | None = None
+    last_modifiers: list[str] = field(default_factory=list)
+    render_policy: Any = None
+
+
+@dataclass
+class Constraints:
+    """
+    A class to represent constraints for the application.
+    """
+    max_width:      int = None
+    max_height:     int = None
+    min_width:      int = None
+    min_height:     int = None

hatui/core/input_manager.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+import os
+import select
+import sys
+
+
+@dataclass
+class InputEvent:
+    event_type: str
+    key: str
+    modifiers: list[str]
+    callback: Callable
+
+
+class InputManager:
+    def __init__(self):
+        self.events: list[InputEvent] = []
+        self.is_windows = os.name == "nt"
+
+    def on(self, event_type: str, key: str, modifiers: list[str], callback: Callable):
+        self.events.append(InputEvent(event_type, key, modifiers, callback))
+
+    def emit_event(self, event_type: str, key: str, modifiers: list[str]):
+        for event in self.events:
+            if event.event_type == event_type and event.key == key and event.modifiers == modifiers:
+                event.callback()
+
+    def poll_input(self, timeout: float = 0.05) -> tuple[str, list[str]] | None:
+        raw = self._read_input(timeout)
+        if raw is None:
+            return None
+        key, modifiers = self._parse_key(raw)
+        self.emit_event("keypress", key, modifiers)
+        return key, modifiers
+
+    def _read_input(self, timeout: float) -> str | None:
+        if self.is_windows:
+            return self._read_input_windows(timeout)
+        return self._read_input_posix(timeout)
+
+    def _read_input_posix(self, timeout: float) -> str | None:
+        fd = sys.stdin.fileno()
+        ready, _, _ = select.select([fd], [], [], timeout)
+        if not ready:
+            return None
+
+        first = os.read(fd, 1).decode(errors="ignore")
+        if first != "\x1b":
+            return first
+        return first + self._read_ready_chars(fd, 0.02, settle_timeout=0.005)
+
+    def _read_ready_chars(self, fd: int, timeout: float, settle_timeout: float = 0.01) -> str:
+        chars: list[str] = []
+        ready, _, _ = select.select([fd], [], [], timeout)
+        while ready:
+            chars.append(os.read(fd, 32).decode(errors="ignore"))
+            ready, _, _ = select.select([fd], [], [], settle_timeout)
+        return "".join(chars)
+
+    def _read_input_windows(self, timeout: float) -> str | None:
+        import time
+        import msvcrt
+
+        deadline = time.monotonic() + max(timeout, 0.0)
+        while time.monotonic() < deadline:
+            if not msvcrt.kbhit():
+                time.sleep(min(0.005, timeout))
+                continue
+            first = msvcrt.getwch()
+            if first in ("\x00", "\xe0"):
+                second = msvcrt.getwch()
+                return self._windows_extended_key(first + second)
+            return first
+        return None
+
+    def _windows_extended_key(self, raw: str) -> str:
+        extended = {
+            "\xe0H": "\x1b[A",
+            "\xe0P": "\x1b[B",
+            "\xe0M": "\x1b[C",
+            "\xe0K": "\x1b[D",
+            "\x00H": "\x1b[A",
+            "\x00P": "\x1b[B",
+            "\x00M": "\x1b[C",
+            "\x00K": "\x1b[D",
+            "\x00\x0f": "\x1b[Z",
+        }
+        return extended.get(raw, raw)
+
+    def _parse_key(self, raw: str) -> tuple[str, list[str]]:
+        if raw == "\x03":
+            raise KeyboardInterrupt("Ctrl+C pressed")
+
+        arrow_map = {
+            "\x1b[A": "up",
+            "\x1b[B": "down",
+            "\x1b[C": "right",
+            "\x1b[D": "left",
+            "\x1bOA": "up",
+            "\x1bOB": "down",
+            "\x1bOC": "right",
+            "\x1bOD": "left",
+        }
+        if raw in arrow_map:
+            return arrow_map[raw], []
+
+        if raw == "\x1b[Z":
+            return "tab", ["shift"]
+
+        if raw == "\t":
+            return "tab", []
+
+        if raw in ("\r", "\n"):
+            return "enter", []
+
+        if raw in ("\x7f", "\b", "\x08"):
+            return "backspace", []
+
+        if raw == " ":
+            return "space", []
+
+        if len(raw) == 2 and raw.startswith("\x1b") and raw[1].isprintable():
+            key = raw[1].lower()
+            modifiers = ["alt"]
+            if raw[1].isalpha() and raw[1].isupper():
+                modifiers.append("shift")
+            return key, modifiers
+
+        if len(raw) == 1 and 0 < ord(raw) < 27:
+            return chr(ord(raw) + 96), ["ctrl"]
+
+        if raw == "\x1b":
+            return "escape", []
+
+        if raw.startswith("\x1b[1;") and raw.endswith(("A", "B", "C", "D")):
+            return self._parse_csi_arrow(raw)
+
+        if raw.startswith("\x1b"):
+            return "escape", []
+
+        modifiers: list[str] = []
+        if raw.isalpha() and raw.isupper():
+            modifiers.append("shift")
+        return raw.lower(), modifiers
+
+    def _parse_csi_arrow(self, raw: str) -> tuple[str, list[str]]:
+        modifier_map = {
+            "2": ["shift"],
+            "3": ["alt"],
+            "4": ["shift", "alt"],
+            "5": ["ctrl"],
+            "6": ["shift", "ctrl"],
+            "7": ["alt", "ctrl"],
+            "8": ["shift", "alt", "ctrl"],
+        }
+        suffix = raw[-1]
+        key = {
+            "A": "up",
+            "B": "down",
+            "C": "right",
+            "D": "left",
+        }[suffix]
+        code = raw[4:-1]
+        return key, modifier_map.get(code, [])

hatui/core/screen_buffer.py

@@ -0,0 +1,150 @@
+import sys
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+
+from hatui.core.style import Style, ansi_sequence
+
+
+@dataclass
+class Cell:
+    """
+    A class to represent a single cell in the screen buffer, aka a single character.
+    """
+    char: str = ' '
+    style: Style = field(default_factory=Style)
+
+
+DEFAULT_STYLE = Style()
+
+class ScreenBuffer:
+    """
+    A class to represent the 2D screen buffer
+    """
+    def __init__(self, width: int, height: int):
+        self.width = width
+        self.height = height
+        self.buffer = [[Cell() for _ in range(width)] for _ in range(height)]
+        self._clip_stack: list[tuple[int, int, int, int]] = []
+        self._style_cache: dict[tuple[str, str], Style] = {("default", "default"): DEFAULT_STYLE}
+
+    def resize(self, width: int, height: int):
+        """
+        Resize the screen buffer to match the current terminal dimensions.
+        """
+        self.width = width
+        self.height = height
+        self.buffer = [[Cell() for _ in range(width)] for _ in range(height)]
+        self._clip_stack.clear()
+
+    def clear(self):
+        """
+        Clear the screen buffer by resetting all cells to default values.
+        """
+        for y in range(self.height):
+            for x in range(self.width):
+                cell = self.buffer[y][x]
+                cell.char = " "
+                cell.style = DEFAULT_STYLE
+
+    def _normalized_clip(self, x: int, y: int, width: int, height: int) -> tuple[int, int, int, int]:
+        left = max(x, 0)
+        top = max(y, 0)
+        right = min(x + max(width, 0), self.width)
+        bottom = min(y + max(height, 0), self.height)
+        if right < left:
+            right = left
+        if bottom < top:
+            bottom = top
+        return left, top, right, bottom
+
+    def push_clip(self, x: int, y: int, width: int, height: int):
+        clip = self._normalized_clip(x, y, width, height)
+        if self._clip_stack:
+            left, top, right, bottom = self._clip_stack[-1]
+            clip = (
+                max(clip[0], left),
+                max(clip[1], top),
+                min(clip[2], right),
+                min(clip[3], bottom),
+            )
+        self._clip_stack.append(clip)
+
+    def pop_clip(self):
+        if self._clip_stack:
+            self._clip_stack.pop()
+
+    @contextmanager
+    def clip(self, x: int, y: int, width: int, height: int):
+        self.push_clip(x, y, width, height)
+        try:
+            yield
+        finally:
+            self.pop_clip()
+
+    def _within_clip(self, x: int, y: int) -> bool:
+        if not self._clip_stack:
+            return True
+        left, top, right, bottom = self._clip_stack[-1]
+        return left <= x < right and top <= y < bottom
+    
+    def _resolve_style(self, fg_color: str, bg_color: str) -> Style:
+        key = (fg_color, bg_color)
+        cached = self._style_cache.get(key)
+        if cached is None:
+            cached = Style(fg_color=fg_color, bg_color=bg_color)
+            self._style_cache[key] = cached
+        return cached
+
+    def write(self, x: int, y: int, char: str, fg_color: str = 'default', bg_color: str = 'default', *, style: Style | None = None):
+        """
+        Write a character to the screen buffer at the specified coordinates.
+        """
+        if 0 <= x < self.width and 0 <= y < self.height and self._within_clip(x, y):
+            cell = self.buffer[y][x]
+            cell.char = char
+            cell.style = style or self._resolve_style(fg_color, bg_color)
+
+    def write_text(self, x: int, y: int, text: str, fg_color: str = 'default', bg_color: str = 'default', *, style: Style | None = None):
+        """
+        Write a string of text to the screen buffer starting at the specified coordinates.
+        """
+        resolved_style = style or self._resolve_style(fg_color, bg_color)
+        for i, char in enumerate(text):
+            self.write(x + i, y, char, fg_color, bg_color, style=resolved_style)
+
+    def write_text_clipped(self, x: int, y: int, text: str, width: int, fg_color: str = "default", bg_color: str = "default", *, style: Style | None = None):
+        self.write_text(x, y, str(text)[: max(width, 0)], fg_color, bg_color, style=style)
+
+    def fill_rect(self, x: int, y: int, width: int, height: int, char: str = " ", fg_color: str = "default", bg_color: str = "default", *, style: Style | None = None):
+        resolved_style = style or self._resolve_style(fg_color, bg_color)
+        fill = char[:1] if char else " "
+        line = fill * max(width, 0)
+        for row in range(max(height, 0)):
+            self.write_text(x, y + row, line, fg_color, bg_color, style=resolved_style)
+
+    def fill_row(self, x: int, y: int, width: int, fg_color: str = "default", bg_color: str = "default", *, style: Style | None = None):
+        self.fill_rect(x, y, width, 1, " ", fg_color, bg_color, style=style)
+
+    def flush(self):
+        """
+        Flush the screen buffer to the terminal.
+        """
+        segments = ["\033[H"]
+        for row_index, row in enumerate(self.buffer):
+            line = [f"\033[{row_index + 1};1H"]
+            active_style = None
+            for cell in row:
+                style = ansi_sequence(cell.style)
+                if style != active_style:
+                    line.append(style)
+                    active_style = style
+                line.append(cell.char)
+            line.append("\033[0m")
+            segments.append("".join(line))
+
+        frame = "".join(segments) + "\033[0m"
+        sys.stdout.write(frame)
+        sys.stdout.flush()
+
+    def to_plain_text(self) -> str:
+        return "\n".join("".join(cell.char for cell in row).rstrip() for row in self.buffer)