echoui 0.9.0__py3-none-any.whl

echoui/__init__.py

@@ -0,0 +1,31 @@
+"""EchoUI public API surface."""
+
+from echoui.app import App
+from echoui.events import on
+from echoui.layout import button, col, row, text
+from echoui.reactive import computed
+from echoui.screen import Screen
+from echoui.signals import signal
+from echoui.sprite import Sprite
+from echoui.stage import Stage
+from echoui.state import Store
+from echoui.style import style
+
+__version__ = "0.9.0"
+
+__all__ = [
+    "App",
+    "Screen",
+    "Stage",
+    "Sprite",
+    "Store",
+    "computed",
+    "signal",
+    "row",
+    "col",
+    "text",
+    "button",
+    "style",
+    "on",
+    "__version__",
+]

echoui/__main__.py

@@ -0,0 +1,3 @@
+from echoui.cli import main
+
+raise SystemExit(main())

echoui/a11y/__init__.py

@@ -0,0 +1,58 @@
+"""Accessibility helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from echoui.sprite import IRNode
+
+
+def aria(label: str, *, role: str | None = None, describedby: str | None = None) -> Dict[str, str]:
+    attrs: Dict[str, str] = {"aria-label": label}
+    if role:
+        attrs["role"] = role
+    if describedby:
+        attrs["aria-describedby"] = describedby
+    return attrs
+
+
+def labelled(node: IRNode, label: str) -> IRNode:
+    node.props.update(aria(label))
+    return node
+
+
+def focus_trap(enabled: bool = True) -> Dict[str, Any]:
+    return {"data-focus-trap": enabled}
+
+
+def skip_link(target: str, label: str = "Skip to content") -> IRNode:
+    return IRNode("link", props={"href": target, "text": label, "class": "skip-link"})
+
+
+def live_region(polite: bool = True) -> Dict[str, str]:
+    return {"aria-live": "polite" if polite else "assertive"}
+
+
+def announce(message: str, *, polite: bool = True) -> Dict[str, str]:
+    attrs = live_region(polite=polite)
+    attrs["data-announce"] = message
+    return attrs
+
+
+def a11y_audit(root: IRNode) -> list[str]:
+    """Rule-based a11y hints (not a WCAG certification)."""
+    issues: list[str] = []
+    interactive = {"button", "input", "link"}
+
+    def walk(node: IRNode) -> None:
+        props = node.props
+        if node.role in interactive:
+            if not props.get("aria-label") and not props.get("label") and not props.get("text"):
+                issues.append(f"{node.id}: interactive role '{node.role}' missing label")
+        if node.role == "image" and not props.get("alt"):
+            issues.append(f"{node.id}: image missing alt text")
+        for child in node.children:
+            walk(child)
+
+    walk(root)
+    return issues

echoui/animation.py

@@ -0,0 +1,95 @@
+"""Tween, spring, and keyframe animations."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+@dataclass
+class Tween:
+    start: float
+    end: float
+    duration: float
+    elapsed: float = 0
+    on_update: Optional[Callable[[float], None]] = None
+    easing: Callable[[float], float] = lambda t: t
+
+    def tick(self, dt: float) -> bool:
+        self.elapsed = min(self.duration, self.elapsed + dt)
+        t = self.elapsed / self.duration if self.duration else 1
+        val = self.start + (self.end - self.start) * self.easing(t)
+        if self.on_update:
+            self.on_update(val)
+        return self.elapsed >= self.duration
+
+
+@dataclass
+class Spring:
+    target: float
+    current: float = 0
+    velocity: float = 0
+    stiffness: float = 180
+    damping: float = 12
+    on_update: Optional[Callable[[float], None]] = None
+
+    def tick(self, dt: float) -> bool:
+        force = -self.stiffness * (self.current - self.target)
+        damp = -self.damping * self.velocity
+        accel = force + damp
+        self.velocity += accel * dt
+        self.current += self.velocity * dt
+        if self.on_update:
+            self.on_update(self.current)
+        return abs(self.current - self.target) < 0.01 and abs(self.velocity) < 0.01
+
+
+@dataclass
+class Keyframe:
+    offset: float
+    props: Dict[str, Any]
+
+
+@dataclass
+class Keyframes:
+    frames: List[Keyframe] = field(default_factory=list)
+    duration: float = 1.0
+    elapsed: float = 0
+
+    def tick(self, dt: float) -> bool:
+        self.elapsed = min(self.duration, self.elapsed + dt)
+        return self.elapsed >= self.duration
+
+    def value_at(self, prop: str) -> Any:
+        if not self.frames:
+            return None
+        return self.frames[-1].props.get(prop)
+
+
+@dataclass
+class Timeline:
+    tweens: List[Tween] = field(default_factory=list)
+
+    def add(self, tween: Tween) -> "Timeline":
+        self.tweens.append(tween)
+        return self
+
+    def tick(self, dt: float) -> bool:
+        return all(t.tick(dt) for t in self.tweens)
+
+
+def tween(start: float, end: float, duration: float, **kwargs: Any) -> Tween:
+    return Tween(start=start, end=end, duration=duration, **kwargs)
+
+
+def spring(target: float, **kwargs: Any) -> Spring:
+    return Spring(target=target, **kwargs)
+
+
+def keyframes(*frames: Keyframe, duration: float = 1.0) -> Keyframes:
+    return Keyframes(frames=list(frames), duration=duration)
+
+
+def ease_out(t: float) -> float:
+    return 1 - math.pow(1 - t, 3)

echoui/api/__init__.py

@@ -0,0 +1,82 @@
+"""HTTP and WebSocket client."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+    import aiohttp
+except ImportError:
+    aiohttp = None  # type: ignore[assignment]
+
+InterceptorFn = Callable[[Dict[str, Any]], Dict[str, Any]]
+
+
+@dataclass
+class ApiClient:
+    base_url: str = ""
+    timeout: float = 30.0
+    retries: int = 1
+    interceptors: List[InterceptorFn] = field(default_factory=list)
+    _session: Any = field(default=None, repr=False)
+
+    async def _get_session(self) -> Any:
+        if aiohttp is None:
+            raise ImportError("aiohttp required; pip install echoui[web]")
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=self.timeout)
+            )
+        return self._session
+
+    async def close(self) -> None:
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        return await self._request("GET", path, **kwargs)
+
+    async def post(self, path: str, **data: Any) -> Any:
+        return await self._request("POST", path, json=data)
+
+    async def upload(self, path: str, field: str, data: bytes, filename: str = "file") -> Any:
+        if aiohttp is None:
+            raise ImportError("aiohttp required")
+        session = await self._get_session()
+        form = aiohttp.FormData()
+        form.add_field(field, data, filename=filename)
+        url = self.base_url + path
+        async with session.post(url, data=form) as resp:
+            return await resp.json()
+
+    async def download(self, path: str) -> bytes:
+        session = await self._get_session()
+        url = self.base_url + path
+        async with session.get(url) as resp:
+            return await resp.read()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        ctx: Dict[str, Any] = {"method": method, "path": path, **kwargs}
+        for ic in self.interceptors:
+            ctx = ic(ctx)
+        session = await self._get_session()
+        url = self.base_url + path
+        last_err: Optional[Exception] = None
+        for attempt in range(self.retries + 1):
+            try:
+                async with session.request(method, url, **kwargs) as resp:
+                    resp.raise_for_status()
+                    ct = resp.headers.get("Content-Type", "")
+                    if "json" in ct:
+                        return await resp.json()
+                    return await resp.text()
+            except Exception as e:
+                last_err = e
+                if attempt < self.retries:
+                    await asyncio.sleep(0.1 * (attempt + 1))
+        raise last_err  # type: ignore[misc]
+
+
+api = ApiClient()

echoui/app.py

@@ -0,0 +1,50 @@
+"""Application root: screens, compile, and dev entry."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Type
+
+from echoui.screen import Screen
+from echoui.sprite import reset_id_gen
+
+
+class App:
+    def __init__(
+        self,
+        screens: List[Type[Screen]],
+        initial: Optional[str] = None,
+        theme: str = "light",
+        color_scheme: str = "auto",
+        title: str = "EchoUI App",
+    ) -> None:
+        self.screens = {s.name or s.__name__: s for s in screens}
+        self.initial = initial or (screens[0].name or screens[0].__name__)
+        self.theme = theme
+        self.color_scheme = color_scheme
+        self.title = title
+        self._current = self.initial
+
+    def switch_screen(self, name: str, effect: str = "none", duration: float = 0.3) -> None:
+        if name not in self.screens:
+            raise KeyError(name)
+        self._current = name
+
+    def build_ir(self) -> Dict[str, Any]:
+        reset_id_gen()
+        screen_cls = self.screens[self._current]
+        screen = screen_cls()
+        return {
+            "app": {"title": self.title, "theme": self.theme, "initial": self.initial},
+            "screen": screen.to_ir().to_dict(),
+            "screens": {n: sc().to_ir().to_dict() for n, sc in self.screens.items()},
+        }
+
+    def compile(self, target: str = "web", out_dir: str = "dist/web", **kwargs: Any) -> str:
+        from echoui.compiler.bundler import build_target
+
+        return build_target(self, target=target, out_dir=out_dir, **kwargs)
+
+    def run(self, host: str = "127.0.0.1", port: int = 7999) -> None:
+        from echoui.cli import dev_server
+
+        dev_server(self, host=host, port=port)

echoui/async_.py

@@ -0,0 +1,17 @@
+"""Async helpers for non-blocking UI work (PLAN § async)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+async def run_in_executor(fn: Callable[[], T]) -> T:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, fn)
+
+
+async def defer(coro: Awaitable[T]) -> T:
+    return await coro

echoui/audio/__init__.py

@@ -0,0 +1 @@
+"""EchoUI package: audio."""

echoui/bridge/__init__.py

@@ -0,0 +1,45 @@
+"""Native and web escape bridges."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+
+class WebApi:
+    """Browser API bridge for escape layer."""
+
+    def __init__(self) -> None:
+        self._listeners: Dict[str, list[Callable[..., None]]] = {}
+
+    def add_event_listener(self, event: str, handler: Callable[..., None]) -> None:
+        self._listeners.setdefault(event, []).append(handler)
+
+    def dispatch(self, event: str, **payload: Any) -> None:
+        for h in self._listeners.get(event, []):
+            h(**payload)
+
+    def local_storage_get(self, key: str) -> Optional[str]:
+        from echoui.storage import local
+
+        return local().get(key)
+
+    def local_storage_set(self, key: str, value: str) -> None:
+        from echoui.storage import local
+
+        local().set(key, value)
+
+
+def web_api() -> WebApi:
+    return WebApi()
+
+
+def os_api() -> Any:
+    from echoui.exceptions import UnsupportedCapability
+
+    raise UnsupportedCapability("os_api is not available on this target")
+
+
+def gpu_api() -> Any:
+    from echoui.exceptions import UnsupportedCapability
+
+    raise UnsupportedCapability("gpu_api is not available on this target")

echoui/camera.py

@@ -0,0 +1,56 @@
+"""Camera for free-layout scenes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional, Tuple
+
+
+@dataclass
+class Camera:
+    x: float = 0
+    y: float = 0
+    zoom: float = 1.0
+    rotation: float = 0
+    follow_target: Optional[str] = None
+    lerp: float = 0.1
+    deadzone: Tuple[float, float] = (0, 0)
+    bounds: Optional[Tuple[float, float, float, float]] = None
+    _shake_t: float = 0
+    _shake_mag: float = 0
+
+    def follow(self, target: Any, *, lerp: float = 0.1, deadzone: Tuple[float, float] = (0, 0)) -> "Camera":
+        name = target if isinstance(target, str) else getattr(target, "id", str(target))
+        self.follow_target = name
+        self.lerp = lerp
+        self.deadzone = deadzone
+        return self
+
+    def zoom_to(self, zoom: float, duration: float = 0) -> "Camera":
+        self.zoom = zoom
+        return self
+
+    def shake(self, magnitude: float, duration: float) -> "Camera":
+        self._shake_mag = magnitude
+        self._shake_t = duration
+        return self
+
+    def tick(self, dt: float, targets: dict[str, tuple[float, float]]) -> None:
+        if self.follow_target and self.follow_target in targets:
+            tx, ty = targets[self.follow_target]
+            self.x += (tx - self.x) * self.lerp
+            self.y += (ty - self.y) * self.lerp
+        if self._shake_t > 0:
+            self._shake_t = max(0, self._shake_t - dt)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "x": self.x,
+            "y": self.y,
+            "zoom": self.zoom,
+            "rotation": self.rotation,
+            "follow": self.follow_target,
+            "lerp": self.lerp,
+            "deadzone": self.deadzone,
+            "bounds": self.bounds,
+        }

echoui/canvas.py

@@ -0,0 +1,31 @@
+"""Canvas rendering helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from echoui.sprite import IRNode
+
+
+@dataclass
+class CanvasLayer:
+    width: int = 800
+    height: int = 600
+    commands: List[Dict[str, Any]] = field(default_factory=list)
+
+    def clear(self, color: str = "#000000") -> None:
+        self.commands.append({"op": "clear", "color": color})
+
+    def fill_rect(self, x: float, y: float, w: float, h: float, color: str) -> None:
+        self.commands.append({"op": "fillRect", "x": x, "y": y, "w": w, "h": h, "color": color})
+
+    def draw_text(self, text: str, x: float, y: float, *, color: str = "#fff", size: int = 16) -> None:
+        self.commands.append({"op": "text", "text": text, "x": x, "y": y, "color": color, "size": size})
+
+    def to_ir(self) -> IRNode:
+        return IRNode("canvas", props={"width": self.width, "height": self.height, "commands": self.commands})
+
+
+def canvas(width: int = 800, height: int = 600) -> CanvasLayer:
+    return CanvasLayer(width=width, height=height)

echoui/chain.py

@@ -0,0 +1,43 @@
+"""Awaitable motion chains for sprites."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, List
+
+
+class MotionChain:
+    def __init__(self, sprite: Any) -> None:
+        self._sprite = sprite
+        self._steps: List[Callable[[], Any]] = []
+
+    def glide_to(self, x: float, y: float, duration: float) -> "MotionChain":
+        sprite = self._sprite
+
+        async def step() -> None:
+            start_x, start_y = sprite.x, sprite.y
+            frames = max(1, int(duration * 60))
+            for i in range(1, frames + 1):
+                t = i / frames
+                sprite.x = start_x + (x - start_x) * t
+                sprite.y = start_y + (y - start_y) * t
+                await asyncio.sleep(duration / frames)
+
+        self._steps.append(step)
+        return self
+
+    def then_(self, other: "MotionChain | Callable[[], Any]") -> "MotionChain":
+        if isinstance(other, MotionChain):
+            self._steps.extend(other._steps)
+        else:
+            self._steps.append(other)
+        return self
+
+    def __await__(self) -> Any:
+        return self._run().__await__()
+
+    async def _run(self) -> None:
+        for step in self._steps:
+            result = step()
+            if asyncio.iscoroutine(result):
+                await result

echoui/cli.py

@@ -0,0 +1,148 @@
+"""EchoUI command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from echoui import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="echoui", description="EchoUI build tool")
+    sub = parser.add_subparsers(dest="cmd")
+
+    sub.add_parser("version", help="Print version")
+
+    new_p = sub.add_parser("new", help="Create a new EchoUI project")
+    new_p.add_argument("name", nargs="?", default="my-app")
+
+    dev_p = sub.add_parser("dev", help="Start dev server")
+    dev_p.add_argument("--target", default="web")
+    dev_p.add_argument("--port", type=int, default=7999)
+    dev_p.add_argument("--host", default="127.0.0.1")
+    dev_p.add_argument("entry", nargs="?", default="main.py")
+
+    build_p = sub.add_parser("build", help="Build for target")
+    build_p.add_argument("--target", default="web", choices=["web", "static", "tui", "desktop", "gui"])
+    build_p.add_argument("--out", default=None)
+    build_p.add_argument("entry", nargs="?", default="main.py")
+
+    sub.add_parser("check", help="Validate project structure")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "version" or args.cmd is None:
+        print(f"echoui {__version__}")
+        return 0
+    if args.cmd == "new":
+        return cmd_new(args.name)
+    if args.cmd == "dev":
+        return cmd_dev(args.entry, host=args.host, port=args.port, target=args.target)
+    if args.cmd == "build":
+        return cmd_build(args.entry, target=args.target, out=args.out)
+    if args.cmd == "check":
+        return cmd_check()
+    parser.print_help()
+    return 1
+
+
+def cmd_new(name: str) -> int:
+    root = Path(name)
+    if root.exists():
+        print(f"Directory exists: {name}")
+        return 1
+    root.mkdir()
+    (root / "main.py").write_text(_COUNTER_TEMPLATE, encoding="utf-8")
+    print(f"Created {name}/main.py")
+    return 0
+
+
+def cmd_build(entry: str, *, target: str, out: str | None) -> int:
+    app = _load_app(entry)
+    out_dir = out or f"dist/{target}"
+    path = app.compile(target=target, out_dir=out_dir)
+    print(f"Built {target} -> {path}")
+    return 0
+
+
+def cmd_dev(entry: str, *, host: str, port: int, target: str) -> int:
+    app = _load_app(entry)
+    dev_server(app, host=host, port=port)
+    return 0
+
+
+def cmd_check() -> int:
+    ok = True
+    for p in ("main.py", "echoui"):
+        if not Path(p).exists():
+            print(f"Missing: {p}")
+            ok = False
+    if ok:
+        print("check: ok")
+    return 0 if ok else 1
+
+
+def _load_app(entry: str) -> Any:
+    import importlib.util
+
+    path = Path(entry).resolve()
+    spec = importlib.util.spec_from_file_location("echoui_entry", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"Cannot load {entry}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    if not hasattr(mod, "app"):
+        raise RuntimeError(f"{entry} must define `app`")
+    return mod.app
+
+
+def dev_server(app: Any, host: str = "127.0.0.1", port: int = 7999) -> None:
+    from aiohttp import web
+
+    out = Path("dist/web")
+    app.compile(target="web", out_dir=str(out))
+
+    async def index(_req: web.Request) -> web.FileResponse:
+        return web.FileResponse(out / "index.html")
+
+    async def static_files(request: web.Request) -> web.FileResponse:
+        return web.FileResponse(out / request.match_info["path"])
+
+    async def action(request: web.Request) -> web.Response:
+        body = await request.json()
+        parsed = __import__("echoui.compiler.parser", fromlist=["parse_app"]).parse_app(app)
+        handler = parsed["handlers"].get(body.get("handler", ""))
+        if handler:
+            handler()
+            app.compile(target="web", out_dir=str(out))
+        return web.json_response({"ok": True})
+
+    srv = web.Application()
+    srv.router.add_get("/", index)
+    srv.router.add_post("/api/action", action)
+    srv.router.add_get("/{path}", static_files)
+    print(f"EchoUI dev server http://{host}:{port}")
+    web.run_app(srv, host=host, port=port, print=None)
+
+
+_COUNTER_TEMPLATE = '''from echoui import App, Screen, Store, col, text, button
+
+class CounterStore(Store):
+    count: int = 0
+
+store = CounterStore()
+
+class Counter(Screen):
+    def build(self):
+        return col(
+            text(lambda: f"Count: {store.count}"),
+            button("+1", on_click=lambda: setattr(store, "count", store.count + 1)),
+        )
+
+app = App(screens=[Counter], initial="Counter")
+'''
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())