millwork 0.1.0__py3-none-any.whl

millwork/testing.py

@@ -0,0 +1,336 @@
+"""Drive an app from a test: the real session, dispatcher, tasks and render, no socket.
+
+``TestApp(app).open(path)`` yields a ``Page`` whose
+actions are events through ``Session.dispatch``; what the server would have
+sent to a tab is collected in ``messages``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import mimetypes
+from collections.abc import AsyncIterator, Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from millwork.auth import Forbidden
+from millwork.files import FileRef, _read_chunks
+from millwork.nodes import Component
+from millwork.protocol import Command, Event, Patch, ServerError, Stream, server_message
+from millwork.session import Session
+from millwork.ui.chat import Chat
+from millwork.ui.files import FileUpload
+from millwork.ui.form import Form
+
+if TYPE_CHECKING:
+    from millwork.app import App
+    from millwork.protocol import Node
+
+# How long to let a handler run between looks at whether it is waiting on the user.
+_TICK = 0.01
+
+
+class Found:
+    """A node of the current tree, with the component that produced it."""
+
+    def __init__(self, node: Node, component: Component | None) -> None:
+        self.id = node.id
+        self.type = node.type
+        self.props = node.props
+        self.children = node.children
+        self.component = component
+
+    @property
+    def rows(self) -> list[dict[str, Any]]:
+        """A Table's rows as the tab receives them."""
+        rows = self.props.get("rows")
+        return list(rows) if isinstance(rows, list) else []
+
+    def __repr__(self) -> str:
+        return f"<{self.type} {self.id}>"
+
+
+class Page:
+    """One open session, driven from the test and observed on its wire."""
+
+    def __init__(self, session: Session[Any]) -> None:
+        self.session = session
+        self.messages: list[Any] = []
+
+    # ------------------------------------------------------------- reading
+
+    @property
+    def tree(self) -> dict[str, Node]:
+        return self.session.tree.nodes if self.session.tree is not None else {}
+
+    @property
+    def state(self) -> Any:
+        return self.session.state
+
+    def find_all(self, what: type[Component] | str) -> list[Found]:
+        """Every node of a component type, or with a key (or a full id)."""
+        tree = self.session.tree
+        if tree is None:
+            return []
+        out = []
+        for node_id, node in tree.nodes.items():
+            if isinstance(what, str):
+                hit = node_id == what or node_id.rsplit("/", 1)[-1] == what
+            else:
+                hit = node.type == what.type
+            if hit:
+                out.append(Found(node, tree.components.get(node_id)))
+        return out
+
+    def find(self, what: type[Component] | str) -> Found:
+        found = self.find_all(what)
+        if not found:
+            name = what if isinstance(what, str) else what.__name__
+            raise LookupError(f"no {name} on the page")
+        return found[0]
+
+    def text(self) -> str:
+        """Every string prop of the tree, for a quick "is it there" check."""
+        parts: list[str] = []
+        for node in self.tree.values():
+            for value in node.props.values():
+                if isinstance(value, str):
+                    parts.append(value)
+        return "\n".join(parts)
+
+    @property
+    def patches(self) -> list[Patch]:
+        return [m for m in self.messages if isinstance(m, Patch)]
+
+    @property
+    def last_patch(self) -> Patch | None:
+        patches = self.patches
+        return patches[-1] if patches else None
+
+    @property
+    def commands(self) -> list[Command]:
+        return [m for m in self.messages if isinstance(m, Command)]
+
+    @property
+    def toasts(self) -> list[str]:
+        return [str(c.args.get("message", "")) for c in self.commands if c.name == "toast"]
+
+    @property
+    def stream(self) -> list[dict[str, Any]]:
+        return [m.chunk for m in self.messages if isinstance(m, Stream)]
+
+    @property
+    def errors(self) -> list[str]:
+        return [m.message for m in self.messages if isinstance(m, ServerError)]
+
+    # ------------------------------------------------------------- acting
+
+    async def event(self, node: Found | str, name: str, payload: Any = None) -> None:
+        """One event through the real dispatcher, then everything it set off."""
+        node_id = node.id if isinstance(node, Found) else self.find(node).id
+        self.session.spawn(
+            self.session.dispatch(Event(node=node_id, name=name, payload=payload)), "test event"
+        )
+        await self.settle()
+
+    async def click(self, node: Found | str) -> None:
+        await self.event(node, "click")
+
+    async def change(self, node: Found | str, value: Any) -> None:
+        await self.event(node, "change", value)
+
+    async def submit(self, form: Found | str, draft: Any) -> None:
+        """Submit a draft (a dict or a model instance) as the tab would."""
+        if hasattr(draft, "model_dump"):
+            draft = draft.model_dump(mode="json")
+        await self.event(form, "submit", draft)
+
+    async def select(self, table: Found | str, keys: list[Any]) -> None:
+        await self.event(table, "select", keys)
+
+    async def action(self, node: Found | str, action: str, key: Any = None) -> None:
+        """A row action on a Table (``[action, key]``) or a card action (``action``)."""
+        await self.event(node, "action", [action, key] if key is not None else action)
+
+    def _store(self, node_id: str, path: Path | str, accept: list[str] | None) -> FileRef:
+        p = Path(path)
+        mime = mimetypes.guess_type(p.name)[0]
+        files = self.session.app.files
+        return files.store(
+            self.session,
+            p.name,
+            _read_chunks(p),
+            mime=mime,
+            max_bytes=files.max_session_bytes,
+            accept=accept,
+            node=node_id,
+        )
+
+    async def upload(
+        self, node: Found | str, path: Path | str, *, field: str | None = None
+    ) -> FileRef:
+        """Put a file into the session for a node, as the upload route would.
+
+        For a ``FileUpload`` the ``upload`` event follows. For a ``Form`` the
+        file is stored for the form and returned, to go into a draft at
+        ``field``'s pointer; the submit then resolves it.
+        """
+        found = node if isinstance(node, Found) else self.find(node)
+        component = found.component
+        accept: list[str] | None = None
+        if isinstance(component, FileUpload):
+            accept = component.accept
+        elif isinstance(component, Form):
+            if field is None:
+                raise ValueError("uploading to a Form takes field=, the file field's pointer")
+        elif not isinstance(component, Chat):
+            raise TypeError(f"{found.type} takes no uploads")
+        ref = self._store(found.id, path, accept)
+        if isinstance(component, FileUpload):
+            await self.event(found, "upload", [ref.model_dump(mode="json")])
+        return ref
+
+    async def send(
+        self,
+        chat: Found | str,
+        text: str,
+        *,
+        files: Iterable[Path | str] = (),
+        command: str | None = None,
+    ) -> None:
+        """A chat turn: the message event with text, attachments and a command."""
+        found = chat if isinstance(chat, Found) else self.find(chat)
+        refs = [self._store(found.id, p, None) for p in files]
+        payload = {
+            "text": text,
+            "files": [r.model_dump(mode="json") for r in refs],
+            "command": command,
+        }
+        await self.event(found, "message", payload)
+
+    async def stop(self, chat: Found | str) -> None:
+        await self.event(chat, "stop")
+
+    async def answer(self, payload: Any = None) -> None:
+        """Answer the open ``ask``: ``True``/``False`` press OK or Cancel, a dict
+        or model submits the form inside, ``None`` closes the dialog."""
+        asks = [a for a in self.session._asks.values() if not a.future.done()]
+        if not asks:
+            raise LookupError("nothing is being asked")
+        ask = asks[-1]
+        prefix = self.session._ask_root(ask.request)
+        inside = [n for n in self.tree.values() if n.id == prefix or n.id.startswith(prefix + "/")]
+        if payload is True or payload is False:
+            label = "ok" if payload else "cancel"
+            button = next((n for n in inside if n.id.rsplit("/", 1)[-1] == label), None)
+            if button is None:
+                raise LookupError(f"the ask has no {label} button")
+            await self.event(button.id, "click")
+            return
+        if payload is None:
+            await self.event(prefix, "close")
+            return
+        form = next((n for n in inside if n.type == "Form"), None)
+        if form is None:
+            raise LookupError("the ask has no form to answer")
+        await self.submit(form.id, payload)
+
+    async def navigate(self, path: str) -> None:
+        await self.session.navigate_to(path)
+        await self.settle()
+
+    async def settle(self) -> None:
+        """Wait until the session has nothing left to do, or is waiting on the user.
+
+        Running tasks and spawned work are awaited; a handler blocked on an
+        open ``ask`` is left there for ``answer``. The coalesced render runs
+        at once rather than after its timer.
+        """
+        s = self.session
+        for _ in range(10_000):
+            await asyncio.sleep(0)
+            await asyncio.sleep(0)
+            asking = any(not a.future.done() for a in s._asks.values())
+            # Delayed tasks (``s.later``) are not waited for; a running task or
+            # handler that is blocked on an open ask is left for ``answer``.
+            running = [t.future for t in s.tasks if t.status == "running"]
+            if running:
+                _, still = await asyncio.wait(running, timeout=_TICK)
+                if not (still and asking):
+                    continue
+            spawned = [t for t in s._spawned if not t.done()]
+            if spawned:
+                _, still = await asyncio.wait(spawned, timeout=_TICK)
+                if not (still and asking):
+                    continue
+            if s._render_scheduled and s._render_handle is not None:
+                s._render_handle.cancel()
+                s._render_scheduled = False
+                s._render_handle = None
+                await s._render()
+                continue
+            return
+        raise RuntimeError("the session did not settle")
+
+
+class TestApp:
+    """Build the app once; open pages as sessions without a socket."""
+
+    __test__ = False  # not a pytest collectable, despite the name
+
+    def __init__(self, app: App) -> None:
+        self.app = app
+        self._started = False
+
+    async def startup(self) -> None:
+        """Run the app's startup hooks, once, before the first page opens."""
+        if self._started:
+            return
+        self._started = True
+        for fn in self.app._startup:
+            result = fn()
+            if asyncio.iscoroutine(result):
+                await result
+
+    async def shutdown(self) -> None:
+        for fn in self.app._shutdown:
+            result = fn()
+            if asyncio.iscoroutine(result):
+                await result
+        self._started = False
+
+    @contextlib.asynccontextmanager
+    async def open(
+        self, path: str = "/", *, user: Any = None, state: Any = None
+    ) -> AsyncIterator[Page]:
+        """Open a page as a new session: connect (unless ``state`` is given), mount, yield."""
+        await self.startup()
+        resolved = self.app.resolve(path)
+        if resolved is None:
+            raise LookupError(f"no page at {path}")
+        page_def, params = resolved
+        if self.app.auth is not None and not page_def.public and user is None:
+            raise Forbidden("Sign in to continue.")
+        session: Session[Any] = Session(self.app, page_def, params, path)
+        session.user = user
+        self.app.sessions[session.id] = session
+        page = Page(session)
+
+        async def send(text: str) -> None:
+            page.messages.append(server_message.validate_python(json.loads(text)["msg"]))
+
+        try:
+            if state is not None:
+                session.state = state
+            else:
+                await session.connect()
+            await session.attach(send, 0)
+            await page.settle()
+            yield page
+        finally:
+            await session.close()
+
+
+__all__ = ["Found", "Page", "TestApp"]

millwork/theme.py

@@ -0,0 +1,338 @@
+"""The theme: one JSON file per app, rendered into the HTML shell by the server.
+
+Tokens use the shadcn vocabulary in CSS colour syntax,
+plus ``success``, ``warning`` and ``info`` for the catalogue's tones. A
+token left out keeps the bundle's default. Fonts are self-hosted from
+``public/``; a font service URL is accepted and logged once. The few
+interface strings the bundle needs are English here; an app in another
+language sets them in its theme file.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+log = logging.getLogger("millwork.theme")
+
+Mode = Literal["light", "dark", "system"]
+Density = Literal["comfortable", "compact"]
+Scrollbars = Literal["auto", "thin"]
+
+COLOUR_TOKENS = (
+    "background",
+    "foreground",
+    "card",
+    "card-foreground",
+    "popover",
+    "popover-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "destructive",
+    "destructive-foreground",
+    "success",
+    "success-foreground",
+    "warning",
+    "warning-foreground",
+    "info",
+    "info-foreground",
+    "border",
+    "input",
+    "ring",
+    "chart-1",
+    "chart-2",
+    "chart-3",
+    "chart-4",
+    "chart-5",
+    "sidebar",
+    "sidebar-foreground",
+    "sidebar-primary",
+    "sidebar-primary-foreground",
+    "sidebar-accent",
+    "sidebar-accent-foreground",
+    "sidebar-border",
+    "sidebar-ring",
+)
+OTHER_TOKENS = ("radius", "font-sans", "font-mono", "font-heading")
+TOKENS = frozenset(COLOUR_TOKENS + OTHER_TOKENS)
+
+# A token value is one CSS value: colours, lengths, font stacks. Nothing that
+# could close the declaration or the style element, and no url().
+_VALUE = re.compile(r"^[A-Za-z0-9 #%().,'\"/+*_-]+$")
+_FORBIDDEN = re.compile(r"url\s*\(|expression\s*\(|@|\\|</", re.IGNORECASE)
+_PATH = re.compile(r"^/(?!/)[A-Za-z0-9._~/-]+$")
+
+STRINGS: dict[str, str] = {
+    "loading": "Loading…",
+    "reconnecting": "Reconnecting…",
+    "session_ended": "This session has ended.",
+    "reload": "Reload",
+    "other_tab": "This page was opened in another tab.",
+    "copied": "Copied",
+    "working": "Working",
+    "thinking": "Thinking",
+    "thought": "Thought",
+    "steps": "{n} steps",
+    "one_step": "1 step",
+    "send": "Send",
+    "stop": "Stop",
+    "attach": "Attach",
+    "remove": "Remove",
+    "copy": "Copy",
+    "you": "You",
+    "assistant": "Assistant",
+    "messages": "Messages",
+    "scroll_to_end": "Scroll to end",
+    "good_response": "Good response",
+    "bad_response": "Bad response",
+    "feedback_prompt": "What could be better?",
+    "skip": "Skip",
+    "regenerate": "Regenerate",
+    "edit": "Edit",
+    "save": "Save",
+    "cancel": "Cancel",
+    "actions": "Actions",
+    "download": "Download",
+    "add": "Add",
+    "choose": "Choose",
+    "search": "Search",
+    "no_results": "No results",
+    "open": "Open",
+    "download_failed": "The download failed.",
+    "filter": "Filter",
+    "all": "All",
+    "min": "Min",
+    "max": "Max",
+    "clear": "Clear",
+    "select_all": "Select all",
+    "select_row": "Select row",
+    "dismiss": "Dismiss",
+    "previous": "Previous",
+    "next": "Next",
+    "wait_for_reply": "Wait for the current reply to finish.",
+    "message_too_long": "The message is too long.",
+    "reply_failed": "The reply failed.",
+    "something_went_wrong": "Something went wrong.",
+    "no_page": "No page at {path}.",
+    "not_found_title": "Page not found",
+    "not_found_text": "There is nothing at {path}.",
+    "forbidden_title": "No access",
+    "forbidden_text": "You may not open this page.",
+    "home": "Home",
+    "try_again": "Try again in a moment.",
+    "page_failed": "The page failed to start.",
+    "render_failed": "The page failed to render.",
+    "too_many_sessions": "Too many open sessions.",
+    "too_many_actions": "Too many actions at once; wait a moment.",
+    "signed_out": "Signed out.",
+    "made_room": "This session made room for a newer one.",
+    "sign_in": "Sign in",
+    "sign_in_hint": "Sign in to continue.",
+    "sign_in_failed": "Sign-in failed",
+    "username": "Username",
+    "password": "Password",
+    "continue_with": "Continue with {provider}",
+    "no_sign_in": "No sign-in method is configured.",
+    "proxy_sign_in": "Sign-in happens before this app, and this request carried no identity.",
+    "proxy_denied": "You are signed in, but this app does not admit you.",
+    "sign_out": "Sign out",
+    "theme": "Theme",
+    "light": "Light",
+    "dark": "Dark",
+    "system": "System",
+    "menu": "Menu",
+}
+
+
+def under(base: str, path: str | None) -> str | None:
+    """A same-origin path as the browser must ask for it: under the app's prefix
+    when the app runs under one. Anything that is not a path is left alone."""
+    if base and path and path.startswith("/"):
+        return base + path
+    return path
+
+
+def _check_path(value: str, what: str) -> str:
+    if not _PATH.match(value):
+        raise ValueError(
+            f"{what} must be a same-origin path such as /public/logo.svg, got {value!r}"
+        )
+    return value
+
+
+class Font(BaseModel):
+    """One ``@font-face``, or one stylesheet link when ``url`` is a font service."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    family: str
+    src: str | None = None
+    url: str | None = None
+    weights: str = "100 900"
+    style: Literal["normal", "italic"] = "normal"
+
+    @model_validator(mode="after")
+    def _one_source(self) -> Font:
+        if (self.src is None) == (self.url is None):
+            raise ValueError("a font takes src (a file under public/) or url (a font service)")
+        if self.src is not None:
+            _check_path(self.src, "font src")
+        if self.url is not None and not self.url.startswith("https://"):
+            raise ValueError("a font url must be https")
+        if not re.match(r"^[A-Za-z0-9 _-]+$", self.family):
+            raise ValueError(f"font family name {self.family!r} has characters CSS cannot take")
+        if not re.match(r"^[0-9 ]+$", self.weights):
+            raise ValueError("font weights is a number or a range such as '100 900'")
+        return self
+
+    def css(self, base: str = "") -> str:
+        assert self.src is not None
+        fmt = {"woff2": "woff2", "woff": "woff", "ttf": "truetype", "otf": "opentype"}.get(
+            self.src.rsplit(".", 1)[-1].lower(), ""
+        )
+        src = f"url({under(base, self.src)})" + (f" format('{fmt}')" if fmt else "")
+        return (
+            f"@font-face{{font-family:'{self.family}';src:{src};"
+            f"font-weight:{self.weights};font-style:{self.style};font-display:swap}}"
+        )
+
+
+class Logo(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    light: str
+    dark: str | None = None
+
+    _light = field_validator("light")(staticmethod(lambda v: _check_path(v, "logo")))
+    _dark = field_validator("dark")(staticmethod(lambda v: v and _check_path(v, "logo")))
+
+
+class Theme(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Mode = "system"
+    fonts: list[Font] = Field(default_factory=list)
+    tokens: dict[Literal["light", "dark"], dict[str, str]] = Field(default_factory=dict)
+    logo: Logo | None = None
+    favicon: str | None = None
+    login_image: str | None = None
+    scrollbars: Scrollbars = "thin"
+    density: Density = "comfortable"
+    locale: str = "en"
+    strings: dict[str, str] = Field(default_factory=dict)
+
+    _favicon = field_validator("favicon")(staticmethod(lambda v: v and _check_path(v, "favicon")))
+    _image = field_validator("login_image")(
+        staticmethod(lambda v: v and _check_path(v, "login_image"))
+    )
+
+    @field_validator("logo", mode="before")
+    @classmethod
+    def _logo_shorthand(cls, v: Any) -> Any:
+        return {"light": v} if isinstance(v, str) else v
+
+    @field_validator("tokens")
+    @classmethod
+    def _known_tokens(cls, tokens: dict[str, dict[str, str]]) -> dict[str, dict[str, str]]:
+        for scheme, values in tokens.items():
+            for name, value in values.items():
+                if name not in TOKENS:
+                    raise ValueError(f"unknown theme token {name!r} in {scheme}")
+                if not _VALUE.match(value) or _FORBIDDEN.search(value):
+                    raise ValueError(f"theme token {name} has a value CSS cannot take: {value!r}")
+        return tokens
+
+    @field_validator("locale")
+    @classmethod
+    def _locale(cls, v: str) -> str:
+        if not re.match(r"^[a-z]{2}(-[A-Za-z]{2,4})?$", v):
+            raise ValueError(f"locale must look like 'nl' or 'en-GB', got {v!r}")
+        return v
+
+    @field_validator("strings")
+    @classmethod
+    def _known_strings(cls, strings: dict[str, str]) -> dict[str, str]:
+        unknown = set(strings) - set(STRINGS)
+        if unknown:
+            raise ValueError(f"unknown interface strings: {sorted(unknown)}")
+        return strings
+
+    @classmethod
+    def load(cls, path: Path) -> Theme:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"{path}: not valid JSON ({exc})") from exc
+        return cls.model_validate(data)
+
+    # ------------------------------------------------------------- rendering
+
+    def css(self, base: str = "") -> str:
+        """The style element's text: font faces, then the two token blocks. ``base``
+        is the path prefix the app runs under, for the font files."""
+        parts = [f.css(base) for f in self.fonts if f.src is not None]
+        light = self.tokens.get("light", {})
+        dark = self.tokens.get("dark", {})
+        for selector, values in ((":root", light), (".dark", dark)):
+            if values:
+                body = ";".join(f"--{name}:{value}" for name, value in values.items())
+                parts.append(f"{selector}{{{body}}}")
+        return "".join(parts)
+
+    def head(self) -> str:
+        """Stylesheet links for font-service fonts; empty for a self-hosted theme."""
+        links = []
+        for f in self.fonts:
+            if f.url is not None:
+                log.warning("theme font %s loads from %s on every page view", f.family, f.url)
+                safe = f.url.replace('"', "%22")
+                links.append(f'<link rel="stylesheet" href="{safe}">')
+        return "".join(links)
+
+    def all_strings(self) -> dict[str, str]:
+        return {**STRINGS, **self.strings}
+
+    def text(self, key: str, **vars: Any) -> str:
+        """A message the server sends to a person, in the theme's words."""
+        s = self.all_strings()[key]
+        for name, value in vars.items():
+            s = s.replace("{" + name + "}", str(value))
+        return s
+
+    def boot(self) -> dict[str, Any]:
+        """What the bundle reads at start. Image paths are the app's own: the
+        bundle puts every same-origin path under the prefix when it renders it."""
+        return {
+            "mode": self.mode,
+            "logo": self.logo.model_dump() if self.logo else None,
+            "login_image": self.login_image,
+            "density": self.density,
+            "scrollbars": self.scrollbars,
+            "locale": self.locale,
+            "strings": self.all_strings(),
+        }
+
+
+def find_theme(public_dir: Path | None) -> Theme:
+    """``public/theme.json`` when the app has one, the default theme otherwise."""
+    if public_dir is not None:
+        candidate = public_dir / "theme.json"
+        if candidate.is_file():
+            theme = Theme.load(candidate)
+            log.info("theme loaded from %s", candidate)
+            return theme
+    return Theme()
+
+
+__all__ = ["Font", "Logo", "STRINGS", "TOKENS", "Theme", "find_theme"]