shadlet 0.1.1__py3-none-any.whl

shadlet/__init__.py

@@ -0,0 +1,260 @@
+"""shadlet: Python-first web applications."""
+
+from shadlet.app import App, Context, RouteMatch, RoutingError
+from shadlet.components import (
+    Accordion,
+    AccordionItem,
+    Alert,
+    AlertDialog,
+    AlertVariant,
+    Align,
+    AspectRatio,
+    Avatar,
+    Badge,
+    BadgeVariant,
+    Breadcrumb,
+    BreadcrumbItem,
+    Button,
+    ButtonGroup,
+    ButtonSize,
+    ButtonVariant,
+    Calendar,
+    CalendarMode,
+    Card,
+    Carousel,
+    Chart,
+    ChartKind,
+    ChartSeries,
+    Checkbox,
+    Code,
+    Collapsible,
+    Combobox,
+    Command,
+    Component,
+    ComponentError,
+    ContextMenu,
+    DataTable,
+    DatePicker,
+    Dialog,
+    Direction,
+    Drawer,
+    DropdownMenu,
+    Empty,
+    Field,
+    Form,
+    Heading,
+    HeadingLevel,
+    HoverCard,
+    Icon,
+    Input,
+    InputGroup,
+    InputOTP,
+    Item,
+    Justify,
+    Kbd,
+    Label,
+    Link,
+    Menubar,
+    MenuGroup,
+    MenuItem,
+    NativeSelect,
+    NavigationItem,
+    NavigationMenu,
+    Orientation,
+    Overflow,
+    Pagination,
+    Popover,
+    Position,
+    Progress,
+    RadioGroup,
+    Resizable,
+    Select,
+    SelectAlign,
+    SelectOption,
+    Separator,
+    Sheet,
+    Side,
+    Sidebar,
+    SidebarItem,
+    SidebarSection,
+    Skeleton,
+    Slider,
+    Spinner,
+    Switch,
+    TabItem,
+    Table,
+    TableColumn,
+    Tabs,
+    Text,
+    Textarea,
+    TextVariant,
+    Theme,
+    ThemeToggle,
+    ToastLevel,
+    Toggle,
+    ToggleGroup,
+    ToggleSize,
+    ToggleVariant,
+    Tooltip,
+    WrapMode,
+)
+from shadlet.components import (
+    Textarea as TextArea,
+)
+from shadlet.events import (
+    ChangeEvent,
+    ClickEvent,
+    Event,
+    NavigateEvent,
+    OpenChangeEvent,
+    SelectEvent,
+    SubmitEvent,
+)
+from shadlet.layout import (
+    Box,
+    Center,
+    Column,
+    Container,
+    Expanded,
+    Grid,
+    GridItem,
+    Positioned,
+    Responsive,
+    Row,
+    ScrollArea,
+    SizedBox,
+    Spacer,
+    Stack,
+    Wrap,
+)
+from shadlet.protocol import PROTOCOL_VERSION
+from shadlet.state import State
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "Accordion",
+    "AccordionItem",
+    "Alert",
+    "AlertDialog",
+    "AlertVariant",
+    "Align",
+    "App",
+    "AspectRatio",
+    "Avatar",
+    "Badge",
+    "BadgeVariant",
+    "Box",
+    "Breadcrumb",
+    "BreadcrumbItem",
+    "Button",
+    "ButtonGroup",
+    "ButtonSize",
+    "ButtonVariant",
+    "Calendar",
+    "CalendarMode",
+    "Card",
+    "Carousel",
+    "Center",
+    "ChangeEvent",
+    "Chart",
+    "ChartKind",
+    "ChartSeries",
+    "Checkbox",
+    "ClickEvent",
+    "Code",
+    "Collapsible",
+    "Column",
+    "Combobox",
+    "Command",
+    "Component",
+    "ComponentError",
+    "Container",
+    "Context",
+    "ContextMenu",
+    "DataTable",
+    "DatePicker",
+    "Dialog",
+    "Direction",
+    "Drawer",
+    "DropdownMenu",
+    "Empty",
+    "Event",
+    "Expanded",
+    "Field",
+    "Form",
+    "Grid",
+    "GridItem",
+    "Heading",
+    "HeadingLevel",
+    "HoverCard",
+    "Icon",
+    "Input",
+    "InputGroup",
+    "InputOTP",
+    "Item",
+    "Justify",
+    "Kbd",
+    "Label",
+    "Link",
+    "MenuGroup",
+    "MenuItem",
+    "Menubar",
+    "NativeSelect",
+    "NavigateEvent",
+    "NavigationItem",
+    "NavigationMenu",
+    "OpenChangeEvent",
+    "Orientation",
+    "Overflow",
+    "Pagination",
+    "Popover",
+    "Position",
+    "Positioned",
+    "Progress",
+    "RadioGroup",
+    "Resizable",
+    "Responsive",
+    "RouteMatch",
+    "RoutingError",
+    "Row",
+    "ScrollArea",
+    "Select",
+    "SelectAlign",
+    "SelectEvent",
+    "SelectOption",
+    "Separator",
+    "Sheet",
+    "Side",
+    "Sidebar",
+    "SidebarItem",
+    "SidebarSection",
+    "SizedBox",
+    "Skeleton",
+    "Slider",
+    "Spacer",
+    "Spinner",
+    "Stack",
+    "State",
+    "SubmitEvent",
+    "Switch",
+    "TabItem",
+    "Table",
+    "TableColumn",
+    "Tabs",
+    "Text",
+    "TextArea",
+    "TextVariant",
+    "Textarea",
+    "Theme",
+    "ThemeToggle",
+    "ToastLevel",
+    "Toggle",
+    "ToggleGroup",
+    "ToggleSize",
+    "ToggleVariant",
+    "Tooltip",
+    "Wrap",
+    "WrapMode",
+]

shadlet/_json.py

@@ -0,0 +1,108 @@
+"""Conversion of Python values into deterministic JSON-compatible values."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import enum
+import math
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class NotSerializableError(TypeError):
+    """Raised when a value cannot be represented by the shadlet protocol."""
+
+
+def to_wire_value(
+    value: Any, *, path: str = "value", _seen: set[int] | None = None
+) -> Any:
+    """Convert ``value`` to a JSON-compatible value.
+
+    Callbacks, components, arbitrary objects and cyclic containers are rejected
+    with a precise path so validation errors are actionable.
+    """
+
+    if value is None or isinstance(value, (bool, str)):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise NotSerializableError(f"{path}: non-finite floats are not supported")
+        return value
+    if isinstance(value, enum.Enum):
+        return to_wire_value(value.value, path=path, _seen=_seen)
+    if isinstance(value, (_dt.datetime, _dt.date, _dt.time)):
+        return value.isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, BaseModel):
+        return to_wire_value(value.model_dump(mode="json"), path=path, _seen=_seen)
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        result: dict[str, Any] = {}
+        for field in dataclasses.fields(value):
+            result[field.name] = to_wire_value(
+                getattr(value, field.name), path=f"{path}.{field.name}", _seen=_seen
+            )
+        return result
+
+    from shadlet.state.state import State
+
+    if isinstance(value, State):
+        return to_wire_value(value.value, path=path, _seen=_seen)
+
+    if _seen is None:
+        _seen = set()
+
+    if isinstance(value, Mapping):
+        marker = id(value)
+        if marker in _seen:
+            raise NotSerializableError(f"{path}: cyclic mappings are not supported")
+        _seen.add(marker)
+        try:
+            mapping_result: dict[str, Any] = {}
+            for key, item in value.items():
+                if not isinstance(key, str):
+                    raise NotSerializableError(f"{path}: mapping keys must be strings")
+                mapping_result[key] = to_wire_value(
+                    item, path=f"{path}.{key}", _seen=_seen
+                )
+            return mapping_result
+        finally:
+            _seen.discard(marker)
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        marker = id(value)
+        if marker in _seen:
+            raise NotSerializableError(f"{path}: cyclic sequences are not supported")
+        _seen.add(marker)
+        try:
+            return [
+                to_wire_value(item, path=f"{path}[{index}]", _seen=_seen)
+                for index, item in enumerate(value)
+            ]
+        finally:
+            _seen.discard(marker)
+
+    if isinstance(value, (set, frozenset)):
+        raise NotSerializableError(
+            f"{path}: sets are not supported because their order is not deterministic"
+        )
+    if callable(value):
+        raise NotSerializableError(
+            f"{path}: callbacks must be passed to an on_* argument, not as data"
+        )
+
+    from shadlet.components.base import Component
+
+    if isinstance(value, Component):
+        raise NotSerializableError(
+            f"{path}: components cannot be used as props; use a named slot or children"
+        )
+    raise NotSerializableError(
+        f"{path}: unsupported value of type {type(value).__name__}"
+    )

shadlet/app/__init__.py

@@ -0,0 +1,4 @@
+from shadlet.app.app import App, PageFunction, Route, RoutingError
+from shadlet.app.context import Context, RouteMatch
+
+__all__ = ["App", "Context", "PageFunction", "Route", "RouteMatch", "RoutingError"]

shadlet/app/app.py

@@ -0,0 +1,225 @@
+"""Application lifecycle, routing and page registration."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from urllib.parse import unquote
+
+from shadlet.app.context import Context, RouteMatch
+from shadlet.components.base import Component
+from shadlet.components.enums import Theme
+from shadlet.protocol.models import RouteInfo
+
+PageFunction = Callable[[Context], Component | Awaitable[Component]]
+
+
+class RoutingError(ValueError):
+    """Invalid route declaration or navigation."""
+
+
+@dataclass(frozen=True, slots=True)
+class Route:
+    pattern: str
+    title: str
+    function: PageFunction
+    regex: re.Pattern[str]
+    static_segments: int
+    param_names: tuple[str, ...]
+
+
+def _normalise_path(path: str) -> str:
+    if not isinstance(path, str) or not path:
+        raise RoutingError("route path must be a non-empty string")
+    if not path.startswith("/"):
+        raise RoutingError(f"route path must start with '/': {path!r}")
+    if "?" in path or "#" in path or " " in path:
+        raise RoutingError(
+            f"route path cannot contain queries, fragments or spaces: {path!r}"
+        )
+    if path != "/" and path.endswith("/"):
+        path = path.rstrip("/") or "/"
+    if "//" in path:
+        raise RoutingError(f"route path cannot contain empty segments: {path!r}")
+    return path
+
+
+def _compile_route(path: str) -> tuple[re.Pattern[str], int, tuple[str, ...]]:
+    path = _normalise_path(path)
+    if path == "/":
+        return re.compile(r"^/$"), 0, ()
+    segments = path.strip("/").split("/")
+    pattern_parts: list[str] = []
+    names: list[str] = []
+    static = 0
+    for segment in segments:
+        match = re.fullmatch(r"\{([A-Za-z_][A-Za-z0-9_]*)\}", segment)
+        if match:
+            name = match.group(1)
+            if name in names:
+                raise RoutingError(f"duplicate route parameter {name!r} in {path!r}")
+            names.append(name)
+            pattern_parts.append(f"(?P<{name}>[^/]+)")
+        else:
+            if "{" in segment or "}" in segment:
+                raise RoutingError(f"invalid route segment {segment!r} in {path!r}")
+            static += 1
+            pattern_parts.append(re.escape(segment))
+    return re.compile("^/" + "/".join(pattern_parts) + "$"), static, tuple(names)
+
+
+class App:
+    """A shadlet application.
+
+    Pages are registered with :meth:`page`. An application instance is served
+    by the web runtime.
+    """
+
+    def __init__(
+        self,
+        title: str = "shadlet app",
+        *,
+        icon: str | None = None,
+        theme: Theme | str = Theme.LIGHT,
+        debug: bool = False,
+        version: str = "0.1.1",
+        toaster: bool = True,
+    ) -> None:
+        if not isinstance(title, str) or not title.strip():
+            raise ValueError("app title must be a non-empty string")
+        if theme not in tuple(Theme) and theme not in {"light", "dark", "system"}:
+            raise ValueError("theme must be 'light', 'dark' or 'system'")
+        self.title = title
+        self.icon = icon
+        self.theme = str(theme)
+        self.debug = bool(debug)
+        self.version = version
+        self.toaster = bool(toaster)
+        self._routes: list[Route] = []
+        self._not_found: PageFunction | None = None
+
+    def page(
+        self,
+        path: str,
+        *,
+        title: str | None = None,
+    ) -> Callable[[PageFunction], PageFunction]:
+        normalised = _normalise_path(path)
+        regex, static_segments, names = _compile_route(normalised)
+
+        def decorator(function: PageFunction) -> PageFunction:
+            if not callable(function):
+                raise RoutingError("page must be a callable")
+            for route in self._routes:
+                if route.pattern == normalised:
+                    raise RoutingError(f"duplicate route {normalised!r}")
+                if route.regex.pattern == regex.pattern:
+                    raise RoutingError(
+                        f"route {normalised!r} conflicts with {route.pattern!r}"
+                    )
+            page_title = title or function.__name__.replace("_", " ").title()
+            self._routes.append(
+                Route(
+                    pattern=normalised,
+                    title=page_title,
+                    function=function,
+                    regex=regex,
+                    static_segments=static_segments,
+                    param_names=names,
+                )
+            )
+            return function
+
+        return decorator
+
+    def not_found(self, function: PageFunction) -> PageFunction:
+        if self._not_found is not None:
+            raise RoutingError("a not-found page is already registered")
+        if not callable(function):
+            raise RoutingError("not-found page must be a callable")
+        self._not_found = function
+        return function
+
+    def routes(self) -> list[RouteInfo]:
+        return [
+            RouteInfo(path=route.pattern, title=route.title) for route in self._routes
+        ]
+
+    def match(self, path: str) -> RouteMatch:
+        requested = _normalise_path(path)
+        for route in sorted(
+            self._routes, key=lambda item: item.static_segments, reverse=True
+        ):
+            match = route.regex.fullmatch(requested)
+            if match:
+                params = {
+                    key: unquote(value) for key, value in match.groupdict().items()
+                }
+                return RouteMatch(
+                    path=requested,
+                    pattern=route.pattern,
+                    title=route.title,
+                    params=params,
+                )
+        return RouteMatch(
+            path=requested,
+            pattern=requested,
+            title="not found",
+            not_found=True,
+        )
+
+    def _function_for(self, match: RouteMatch) -> PageFunction:
+        if match.not_found:
+            if self._not_found is not None:
+                return self._not_found
+            return _default_not_found
+        for route in self._routes:
+            if route.pattern == match.pattern:
+                return route.function
+        raise RoutingError(f"no page registered for {match.pattern!r}")
+
+    async def render_page(self, match: RouteMatch, context: Context) -> Component:
+        function = self._function_for(match)
+        result = function(context)
+        if inspect.isawaitable(result):
+            result = await result
+        if not isinstance(result, Component):
+            raise TypeError(
+                f"page {function.__name__!r} returned {type(result).__name__}; "
+                "expected a shadlet Component"
+            )
+        return result
+
+    def run(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 8000,
+        reload: bool = False,
+    ) -> None:
+        import os
+
+        from shadlet.web.server import run_app
+
+        target_port = int(os.environ.get("SHADLET_PORT", str(port)))
+        run_app(self, host=host, port=target_port, reload=reload)
+
+
+def _default_not_found(context: Context) -> Component:
+    from shadlet.components.display import Card
+    from shadlet.components.typography import Heading, Text
+    from shadlet.layout.layout import Center
+
+    return Center(
+        Card(
+            Heading("page not found", level=1),
+            Text(f"no route matches {context.path}", variant="muted"),
+        ),
+        min_height="60vh",
+        padding=24,
+    )
+
+
+__all__ = ["App", "PageFunction", "Route", "RoutingError"]

shadlet/app/context.py

@@ -0,0 +1,90 @@
+"""Application context passed to page functions."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from shadlet.components.enums import ToastLevel
+from shadlet.protocol.models import ToastMessage
+from shadlet.state.state import State
+
+if TYPE_CHECKING:
+    from shadlet.runtime.session import Session
+
+
+@dataclass(frozen=True, slots=True)
+class RouteMatch:
+    path: str
+    pattern: str
+    title: str
+    params: dict[str, str] = field(default_factory=dict)
+    not_found: bool = False
+
+
+class Context:
+    """Per-request context with session-isolated state and navigation."""
+
+    __slots__ = ("_session", "params", "route")
+
+    def __init__(self, session: Session, route: RouteMatch) -> None:
+        self._session = session
+        self.route = route
+        self.params = route.params
+
+    @property
+    def path(self) -> str:
+        return self.route.path
+
+    def state(self, initial: Any, *, key: str | None = None) -> State[Any]:
+        """Return a session-scoped reactive state slot.
+
+        Without an explicit key the slot is keyed by the calling source
+        location, so moving a line of code intentionally creates a new slot.
+        """
+
+        if key is not None:
+            if not isinstance(key, str) or not key:
+                raise ValueError("state key must be a non-empty string")
+            full_key = f"{self.route.pattern}:{key}"
+        else:
+            frame = inspect.currentframe()
+            caller = frame.f_back if frame is not None else None
+            while caller is not None and caller.f_code.co_filename == __file__:
+                caller = caller.f_back
+            if caller is None:
+                raise RuntimeError("could not determine state call site")
+            full_key = (
+                f"{self.route.pattern}:{caller.f_code.co_filename}:{caller.f_lineno}"
+            )
+        return self._session.state_store.get(
+            full_key,
+            initial,
+            self._session.state_changed,
+        )
+
+    def toast(
+        self,
+        message: str,
+        *,
+        description: str | None = None,
+        level: ToastLevel | str = ToastLevel.DEFAULT,
+        duration: int | None = None,
+    ) -> None:
+        if not isinstance(message, str) or not message:
+            raise ValueError("toast message must be a non-empty string")
+        self._session.send_toast(
+            ToastMessage(
+                level=str(level),  # type: ignore[arg-type]
+                message=message,
+                description=description,
+                duration=duration,
+            )
+        )
+
+    def navigate(self, path: str) -> None:
+        self._session.request_navigation(path)
+
+
+__all__ = ["Context", "RouteMatch"]