hatui-kit 0.1.0__py3-none-any.whl

hatui/providers/helpers.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from hatui.runtime.bindings import resolve_path
+from hatui.runtime.formatters import apply_formatter, apply_template
+
+_MISSING = object()
+
+def resolve_value_spec(
+    spec: Any,
+    data: dict[str, Any],
+    *,
+    current: Any = None,
+    default: Any = None,
+    string_mode: str = "path",
+) -> Any:
+    if isinstance(spec, Mapping):
+        value = _resolve_mapping_value(
+            spec,
+            data,
+            current=current,
+            default=default,
+            string_mode=string_mode,
+        )
+        operations = spec.get("operations", [])
+        if operations:
+            value = apply_operations(value, operations, data)
+        return value
+
+    if isinstance(spec, str):
+        resolved = resolve_path(data, spec, _MISSING)
+        if resolved is not _MISSING:
+            return resolved
+        if string_mode == "literal_fallback":
+            return spec
+        if string_mode == "literal":
+            return spec
+        return default
+
+    if spec is None:
+        return default
+
+    return spec
+
+
+def resolve_mapping(
+    mapping: Mapping[str, Any],
+    data: dict[str, Any],
+    *,
+    current: Any = None,
+    string_mode: str = "path",
+) -> dict[str, Any]:
+    return {
+        key: resolve_value_spec(source, data, current=current, string_mode=string_mode)
+        for key, source in mapping.items()
+    }
+
+
+def resolve_items(
+    items: list[Any],
+    data: dict[str, Any],
+    *,
+    current: Any = None,
+    string_mode: str = "literal_fallback",
+) -> list[Any]:
+    resolved: list[Any] = []
+    for item in items:
+        if isinstance(item, Mapping):
+            resolved.append(resolve_mapping(item, data, current=current, string_mode=string_mode))
+        else:
+            resolved.append(resolve_value_spec(item, data, current=current, string_mode=string_mode))
+    return resolved
+
+
+def render_template(template: str, mapping: Mapping[str, Any], data: dict[str, Any], *, current: Any = None) -> str:
+    values = resolve_mapping(mapping, data, current=current, string_mode="path")
+    return template.format(**values)
+
+
+def apply_operations(value: Any, operations: list[Any], data: dict[str, Any]) -> Any:
+    current = value
+    for operation in operations:
+        if not isinstance(operation, Mapping):
+            continue
+        name = operation.get("name")
+        if name == "path":
+            current = resolve_path(current, operation.get("path"), operation.get("default"))
+        elif name == "default":
+            if current is None:
+                current = operation.get("value")
+        elif name == "formatter":
+            formatter = operation.get("formatter")
+            if formatter is None:
+                formatter = {key: item for key, item in operation.items() if key != "name"}
+            current = apply_formatter(current, formatter)
+        elif name == "template":
+            current = apply_template(current, operation.get("template"))
+        elif name == "sort":
+            current = _sort_values(current, operation)
+        elif name == "reverse":
+            if isinstance(current, list):
+                current = list(reversed(current))
+        elif name == "slice":
+            if isinstance(current, (list, str)):
+                start = operation.get("start")
+                end = operation.get("end")
+                current = current[slice(start, end)]
+        elif name == "take":
+            if isinstance(current, list):
+                current = current[: int(operation.get("count", 0))]
+        elif name == "join":
+            separator = operation.get("separator", ", ")
+            if isinstance(current, list):
+                current = separator.join(str(item) for item in current)
+        elif name == "mapping":
+            current = resolve_mapping(operation.get("mapping", {}), data, current=current, string_mode="path")
+        elif name == "template_map":
+            current = render_template(
+                operation.get("template", ""),
+                operation.get("mapping", {}),
+                data,
+                current=current,
+            )
+        elif name == "items":
+            current = resolve_items(operation.get("items", []), data, current=current, string_mode="literal_fallback")
+    return current
+
+
+def _resolve_mapping_value(
+    spec: Mapping[str, Any],
+    data: dict[str, Any],
+    *,
+    current: Any,
+    default: Any,
+    string_mode: str,
+) -> Any:
+    if "value" in spec:
+        value = spec.get("value")
+    elif spec.get("current") is True:
+        value = current
+    elif "path" in spec or "source" in spec:
+        value = resolve_path(data, spec.get("path") or spec.get("source"), spec.get("default", default))
+    elif "mapping" in spec and "template" in spec:
+        value = render_template(spec.get("template", ""), spec.get("mapping", {}), data, current=current)
+    elif "mapping" in spec:
+        value = resolve_mapping(spec.get("mapping", {}), data, current=current, string_mode=string_mode)
+    elif "items" in spec:
+        value = resolve_items(spec.get("items", []), data, current=current, string_mode="literal_fallback")
+    else:
+        value = default
+
+    if "formatter" in spec:
+        value = apply_formatter(value, spec.get("formatter"))
+    if "template" in spec and "mapping" not in spec:
+        value = apply_template(value, spec.get("template"))
+    return value
+
+
+def _sort_values(value: Any, operation: Mapping[str, Any]) -> Any:
+    if not isinstance(value, list):
+        return value
+
+    reverse = bool(operation.get("reverse", False))
+    key_path = operation.get("path")
+    if key_path:
+        return sorted(value, key=lambda item: resolve_path(item, key_path), reverse=reverse)
+    return sorted(value, reverse=reverse)

hatui/runtime/__init__.py

@@ -0,0 +1,24 @@
+"""Runtime utilities for declarative Hatui apps."""
+
+from hatui.runtime.action_registry import ActionRegistry, create_default_action_registry
+from hatui.runtime.bindings import resolve_path, set_path
+from hatui.runtime.formatters import apply_formatter
+from hatui.runtime.loader import ScreenSpecLoader
+from hatui.runtime.provider_manager import ProviderManager
+from hatui.runtime.registries import ProviderRegistry, WidgetRegistry
+from hatui.runtime.router import Router
+from hatui.runtime.store import Store
+
+__all__ = [
+    "ActionRegistry",
+    "ProviderManager",
+    "ProviderRegistry",
+    "Router",
+    "ScreenSpecLoader",
+    "Store",
+    "WidgetRegistry",
+    "apply_formatter",
+    "create_default_action_registry",
+    "resolve_path",
+    "set_path",
+]

hatui/runtime/action_registry.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+ActionHandler = Callable[[Any, dict[str, Any], Any], bool]
+
+
+@dataclass(slots=True)
+class ActionRegistry:
+    handlers: dict[str, ActionHandler]
+
+    def __init__(self):
+        self.handlers = {}
+
+    def register(self, action: str, handler: ActionHandler) -> None:
+        self.handlers[action] = handler
+
+    def dispatch(self, action: str, source, payload: dict[str, Any], context) -> bool:
+        handler = self.handlers.get(action)
+        if handler is None:
+            return bool(source.handle_action(action, payload, context))
+        return bool(handler(source, payload, context))
+
+
+def create_default_action_registry() -> ActionRegistry:
+    registry = ActionRegistry()
+    registry.register("focus_next", _focus_next)
+    registry.register("focus_prev", _focus_prev)
+    registry.register("focus_first", _focus_first)
+    registry.register("focus_last", _focus_last)
+    registry.register("focus_widget", _focus_widget)
+    registry.register("route_set", _route_set)
+    registry.register("route_next", _route_next)
+    registry.register("route_prev", _route_prev)
+    registry.register("route_push", _route_push)
+    registry.register("route_pop", _route_pop)
+    registry.register("route_pop_focus_widget", _route_pop_focus_widget)
+    registry.register("store_set", _store_set)
+    registry.register("store_toggle", _store_toggle)
+    return registry
+
+
+def _interaction(source):
+    root = source.root
+    interaction = getattr(root, "interaction", None)
+    if interaction is None:
+        raise RuntimeError("Root widget missing interaction controller")
+    return interaction
+
+
+def _focus_next(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).focus_next(context)
+
+
+def _focus_prev(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).focus_prev(context)
+
+
+def _focus_first(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).focus_first(context)
+
+
+def _focus_last(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).focus_last(context)
+
+
+def _focus_widget(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).focus_widget(payload.get("target"), context)
+
+
+def _route_set(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_set(payload.get("route"), context)
+
+
+def _route_next(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_next(context)
+
+
+def _route_prev(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_prev(context)
+
+
+def _route_push(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_push(payload.get("route"), context)
+
+
+def _route_pop(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_pop(context)
+
+
+def _route_pop_focus_widget(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).route_pop_focus_widget(payload.get("target"), context)
+
+
+def _store_set(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).store_set(payload.get("path"), payload.get("value"), context)
+
+
+def _store_toggle(source, payload: dict[str, Any], context) -> bool:
+    return _interaction(source).store_toggle(payload.get("path"), context)

hatui/runtime/bindings.py

@@ -0,0 +1,40 @@
+from collections.abc import Mapping
+from typing import Any
+
+
+def resolve_path(data: Any, path: str | None, default: Any = None) -> Any:
+    if path is None or path == "":
+        return default
+
+    current = data
+    for part in path.split("."):
+        if isinstance(current, Mapping):
+            if part not in current:
+                return default
+            current = current[part]
+            continue
+
+        if isinstance(current, list):
+            try:
+                index = int(part)
+            except ValueError:
+                return default
+            if index < 0 or index >= len(current):
+                return default
+            current = current[index]
+            continue
+
+        return default
+    return current
+
+
+def set_path(data: dict[str, Any], path: str, value: Any):
+    parts = path.split(".")
+    current: dict[str, Any] = data
+    for part in parts[:-1]:
+        next_value = current.get(part)
+        if not isinstance(next_value, dict):
+            next_value = {}
+            current[part] = next_value
+        current = next_value
+    current[parts[-1]] = value

hatui/runtime/bootstrap.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from hatui.runtime.loader import ScreenSpecLoader
+from hatui.runtime.provider_manager import ProviderManager
+from hatui.runtime.render_policy import RenderPolicy
+from hatui.runtime.router import Router
+from hatui.runtime.store import Store
+from hatui.widgets.root_widget import RootWidget
+
+
+@dataclass
+class BootstrapResult:
+    store: Store
+    router: Router
+    root_widget: RootWidget
+    provider_manager: ProviderManager
+    loaded_files: list[Path]
+    dev_spec: dict[str, Any]
+
+
+def merge_state(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = deepcopy(base)
+    for key, value in incoming.items():
+        if key not in merged:
+            merged[key] = deepcopy(value)
+            continue
+        if isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = merge_state(dict(merged[key]), value)
+        else:
+            merged[key] = deepcopy(value)
+    return merged
+
+
+def build_runtime(
+    *,
+    spec_path: Path,
+    loader: ScreenSpecLoader,
+    preserved_state: dict[str, Any] | None = None,
+    preserved_stack: list[str] | None = None,
+    preserved_focus: str | None = None,
+    preserved_focus_map: dict[str, str] | None = None,
+    glyph_mode: str = "unicode",
+) -> BootstrapResult:
+    spec = loader.load_spec(spec_path)
+    theme = loader.load_theme(spec)
+    initial_state = loader.load_state(spec)
+    router_spec = loader.load_router(spec)
+    dev_spec = loader.load_dev(spec)
+    screen = loader.load_screen(spec)
+    providers = loader.load_providers(spec)
+
+    merged_state = merge_state(initial_state, preserved_state or {})
+    store = Store(initial_state=merged_state)
+    router = Router(
+        routes=list(router_spec.get("routes", []) or []),
+        initial=router_spec.get("initial"),
+    )
+    if preserved_stack:
+        stack = [route for route in preserved_stack if router.has_route(route)]
+        if not stack and router.current:
+            stack = [router.current]
+        if stack:
+            router.stack = stack
+
+    root_widget = RootWidget(
+        "root",
+        children=[screen],
+        theme=theme,
+        store=store,
+        router=router,
+        render_policy=RenderPolicy(glyph_mode=glyph_mode),
+    )
+    if preserved_focus_map:
+        root_widget.state["last_focused_by_route"] = dict(preserved_focus_map)
+    if preserved_focus:
+        root_widget.context.focused_widget = preserved_focus
+    root_widget.focus_first(root_widget.context)
+    if preserved_focus:
+        root_widget.context.focused_widget = preserved_focus
+    root_widget.sync_focus(root_widget.context)
+
+    return BootstrapResult(
+        store=store,
+        router=router,
+        root_widget=root_widget,
+        provider_manager=ProviderManager(providers),
+        loaded_files=list(loader.last_loaded_files),
+        dev_spec=dev_spec,
+    )

hatui/runtime/cli.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from contextlib import nullcontext
+from pathlib import Path
+
+from hatui.demo_assets import bundled_demo_spec_path
+from hatui.runtime.render_policy import RenderPolicy
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hatui")
+    subparsers = parser.add_subparsers(dest="command")
+
+    run_parser = subparsers.add_parser("run")
+    run_parser.add_argument("spec", nargs="?", help="path to YAML spec")
+    run_parser.add_argument("--watch", action="store_true", help="reload spec when watched files change")
+
+    validate_parser = subparsers.add_parser("validate")
+    validate_parser.add_argument("spec", nargs="?", help="path to YAML spec")
+
+    preview_parser = subparsers.add_parser("preview")
+    preview_parser.add_argument("spec", nargs="?", help="path to YAML spec")
+    preview_parser.add_argument("--route")
+    preview_parser.add_argument("--width", type=int, default=100)
+    preview_parser.add_argument("--height", type=int, default=32)
+    preview_parser.add_argument("--frames", type=int, default=1)
+    return parser
+
+
+def normalize_argv(argv: list[str] | None = None) -> list[str]:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] not in {"run", "validate", "preview"}:
+        return ["run", *argv]
+    return argv
+
+
+def resolve_spec_context(spec_arg: str | None):
+    if spec_arg:
+        return nullcontext(Path(spec_arg)), False
+    return bundled_demo_spec_path(), True
+
+
+def preferred_glyph_mode(stream=None) -> str:
+    stream = sys.stdout if stream is None else stream
+    encoding = getattr(stream, "encoding", None) or "utf-8"
+    sample = "┌█▁░▸●╱"
+    try:
+        sample.encode(encoding)
+    except UnicodeEncodeError:
+        return "ascii"
+    return "unicode"
+
+
+def write_cli_text(text: str) -> None:
+    encoding = sys.stdout.encoding or "utf-8"
+    try:
+        sys.stdout.write(text)
+    except UnicodeEncodeError:
+        fallback = RenderPolicy("ascii").translate(text)
+        if hasattr(sys.stdout, "buffer"):
+            sys.stdout.buffer.write(fallback.encode(encoding, errors="replace"))
+        else:
+            sys.stdout.write(fallback)
+    sys.stdout.flush()