hatui-kit 0.1.0__tar.gz

hatui_kit-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+# Python-based stuff
+*.pyc
+.venv
+build/
+dist/
+*.egg-info
+
+.codex/

hatui_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hatui contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hatui_kit-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hatui-kit
+Version: 0.1.0
+Summary: A configurable hacker-style terminal UI toolkit driven by YAML screens, widgets, and providers.
+Project-URL: Homepage, https://github.com/almajd3713/hacker_tui_sim
+Project-URL: Repository, https://github.com/almajd3713/hacker_tui_sim
+Project-URL: Issues, https://github.com/almajd3713/hacker_tui_sim/issues
+Author: almajd3713
+License: MIT License
+        
+        Copyright (c) 2026 Hatui contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,dashboard,terminal,tui,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# Hatui
+
+Hatui is a configurable hacker-style terminal UI toolkit for Python. It lets you compose full-screen TUIs from YAML screens, reusable widgets, themes, routing, and data providers.
+
+## Install
+
+Recommended for end users:
+
+```bash
+pipx install hatui-kit
+```
+
+Python package install:
+
+```bash
+pip install hatui-kit
+```
+
+Installed CLI command:
+
+```bash
+hatui
+```
+
+Windows convenience build:
+
+- Download `hatui-windows-amd64.zip` from GitHub Releases
+- Unzip it
+- Run `hatui.exe`
+
+## Quick start
+
+Run the bundled demo:
+
+```bash
+hatui
+```
+
+Validate the bundled demo spec:
+
+```bash
+hatui validate
+```
+
+Render a non-interactive preview:
+
+```bash
+hatui preview --width 100 --height 28 --frames 1
+```
+
+Run a custom spec:
+
+```bash
+hatui run path/to/screen.yaml
+```
+
+## What Hatui provides
+
+- declarative YAML screen loading with includes
+- widget and provider registries
+- routing, modals, focus traversal, and debug overlays
+- theme slots, color tokens, and font tokens
+- reusable hacker-style widgets for dashboards and console simulations
+
+## Example custom spec
+
+```yaml
+theme:
+  preset: clean_ops
+
+providers:
+  - type: constant
+    name: hello_text
+    target: ui.hello
+    value: Hello from Hatui
+
+screen:
+  type: box
+  name: root_box
+  title: demo
+  padding: 1
+  child:
+    type: text
+    name: hello_text
+    text_key: ui.hello
+```
+
+Run it with:
+
+```bash
+hatui run ./demo.yaml
+```
+
+## Development
+
+Editable install:
+
+```bash
+python -m pip install -e .
+```
+
+Smoke checks:
+
+```bash
+python -m compileall src
+PYTHONPATH=src python -m hatui validate
+PYTHONPATH=src python -m hatui preview --width 100 --height 28 --frames 1
+```

hatui_kit-0.1.0/README.md

@@ -0,0 +1,108 @@
+# Hatui
+
+Hatui is a configurable hacker-style terminal UI toolkit for Python. It lets you compose full-screen TUIs from YAML screens, reusable widgets, themes, routing, and data providers.
+
+## Install
+
+Recommended for end users:
+
+```bash
+pipx install hatui-kit
+```
+
+Python package install:
+
+```bash
+pip install hatui-kit
+```
+
+Installed CLI command:
+
+```bash
+hatui
+```
+
+Windows convenience build:
+
+- Download `hatui-windows-amd64.zip` from GitHub Releases
+- Unzip it
+- Run `hatui.exe`
+
+## Quick start
+
+Run the bundled demo:
+
+```bash
+hatui
+```
+
+Validate the bundled demo spec:
+
+```bash
+hatui validate
+```
+
+Render a non-interactive preview:
+
+```bash
+hatui preview --width 100 --height 28 --frames 1
+```
+
+Run a custom spec:
+
+```bash
+hatui run path/to/screen.yaml
+```
+
+## What Hatui provides
+
+- declarative YAML screen loading with includes
+- widget and provider registries
+- routing, modals, focus traversal, and debug overlays
+- theme slots, color tokens, and font tokens
+- reusable hacker-style widgets for dashboards and console simulations
+
+## Example custom spec
+
+```yaml
+theme:
+  preset: clean_ops
+
+providers:
+  - type: constant
+    name: hello_text
+    target: ui.hello
+    value: Hello from Hatui
+
+screen:
+  type: box
+  name: root_box
+  title: demo
+  padding: 1
+  child:
+    type: text
+    name: hello_text
+    text_key: ui.hello
+```
+
+Run it with:
+
+```bash
+hatui run ./demo.yaml
+```
+
+## Development
+
+Editable install:
+
+```bash
+python -m pip install -e .
+```
+
+Smoke checks:
+
+```bash
+python -m compileall src
+PYTHONPATH=src python -m hatui validate
+PYTHONPATH=src python -m hatui preview --width 100 --height 28 --frames 1
+```

hatui_kit-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hatui-kit"
+version = "0.1.0"
+description = "A configurable hacker-style terminal UI toolkit driven by YAML screens, widgets, and providers."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = ["PyYAML>=6.0"]
+authors = [
+  { name = "almajd3713" },
+]
+keywords = ["tui", "terminal", "dashboard", "yaml", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: User Interfaces",
+  "Topic :: Terminals",
+]
+
+[project.urls]
+Homepage = "https://github.com/almajd3713/hacker_tui_sim"
+Repository = "https://github.com/almajd3713/hacker_tui_sim"
+Issues = "https://github.com/almajd3713/hacker_tui_sim/issues"
+
+[project.scripts]
+hatui = "hatui.app:main"
+
+[tool.hatch.build]
+include = [
+  "src/hatui/**/*.py",
+  "src/hatui/demo/screens/**/*.yaml",
+  "README.md",
+  "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hatui"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/hatui",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.uv]
+package = true

hatui_kit-0.1.0/src/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_kit-0.1.0/src/hatui/__main__.py

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

hatui_kit-0.1.0/src/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_kit-0.1.0/src/hatui/core/__init__.py

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

hatui_kit-0.1.0/src/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_kit-0.1.0/src/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