Cheat sheet¶

from __future__ import annotations          # required
from situ import Local, Url, Server        # + Synced, Prop, Emit, Provide, Inject

search: Local[str] = ""
tags: Local[set] = set()                    # Local[set] is first-class
filter: Url[str] = "all"
issues: Server[IssuesFacade]                # Protocol under TYPE_CHECKING

def clear():                                # no await → compiled to client JS
    global search                           # bare-name signal write: declare global
    search = ""

async def close(id):                        # await → POST /cmd/close/{id}
    await issues.set_status(id, "closed")
    reset("search")                         # injected: back to defaults, rides the response
    signal("toast", "Closed")               # injected: push a value into a client signal

# Litestar (the reference adapter; from `situ`) — lazily imported, no Litestar until called
mount_static_component(path=, stem=, template=, meta=)              # pure client
mount_component(path=, stem=, template=, meta=,                     # + commands, DI, server render
                service_type=Store, context=ctx,                    # Litestar mount: Dishka container
                components=Context.from_dir(DIR),                   # optional tree
                live=True, window_template=..., unified=True,       # opt-ins
                hub=Hub(),                                          # publish from outside a request
                fallback="<p>Unavailable.</p>")                     # region markup if the render raises
mount_component(path="/things/{id:int}", ...)                      # entity mount: view["id"] from the path, one island
mount_tree(path=, root=, components=, template=, meta=)             # pure-client tree

# Any ASGI host (FastAPI / Starlette / uvicorn) — imports no web framework, no extra dependency
from situ.mount.asgi import asgi_app
app.mount("/board", asgi_app(app_factory=lambda cmd: compile_mount(STEM, cmd), template=, meta=,
                             resolve=lambda: store, context=ctx))   # resolve may be sync or async

# Flask (from `situ.mount.flask`, in situ[flask]) — a Blueprint, no Dishka, no Litestar
mount_flask(path=, app_factory=lambda cmd: compile_app(front, cmd), template=, meta=,
            resolve=lambda: store, context=ctx, facade=Store,
            guard=require_login,                                    # before_request: per-mount auth
            head='<link rel=stylesheet href=/static/declui.css>')   # declui scaffold styling
# CSRF: command POSTs must carry the shim's `X-Siting: 1` header (enforced) — csrf.exempt(bp) form-CSRF

ctx = situ_ui.kit().merge(Context.from_dir(COMPONENTS)).with_override("Toast", stem)

class Issue:  # @dataclass / attrs / msgspec / pydantic / SQLAlchemy (info={"declui": Field(...)})
    id: Annotated[int, Field(hidden=True)]
    title: Annotated[str, Field(label_field=True, search=True)]
    status: Status                                    # Enum → <select>
    owner: User | None                                # reference → <select>/Combobox
    notes: list[Note]                                 # one-to-many, read-only
    bio: Annotated[str, Field(widget="RichText", editable="rating > 50")]
    place: Annotated[str, Field(widget="custom", control="<div…>", binds=("lat","lng"))]  # composite: 1 control, N attrs
    loc: Annotated[str, Field(widget="custom", component="CountryCity", binds=("country","city"))]  # linked: a real component (has handlers) + mount_model(components=Context…)

    @action(label="Close", visible="status == 'open'", message="Closed")  # async → per-row command
    async def close(self):
        return Redirect("/done")                        # optional: navigate on success

mount_model(path=, screen=Screen(model=Issue, zones={...}),          # form (default)
            screens=("list","detail"), rows=[...], choices={...})    # client modes
mount_model(path=, screen=, service_type=, facade=, context=)        # server tracker
mount_model(path="/new", screen=, screens=("create",), service_type=, facade=, after="/")  # create form
mount_model(path="/{id:int}/edit", screen=, screens=("edit",), service_type=, facade=, context=, after="/")  # edit