shinyreact 0.1.0__py3-none-any.whl

shinyreact/_app.py

@@ -0,0 +1,205 @@
+"""``shinyreact.ReactApp``: a ``shiny.App`` whose UI is discovered, not passed.
+
+``shiny.App`` accepts the full-document UI itself via ``ui.page_html()``
+(py-shiny#2475). ``ReactApp`` adds the two things it does not do: discover the
+ui.tsx-pattern UI next to the app file, and serve the sibling assets a full
+document references.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from shiny import App as _ShinyApp
+from shiny.types import MISSING, MISSING_TYPE
+
+from ._dep import ShinyreactJs, _serves_bundle
+
+if TYPE_CHECKING:
+    StaticAssets = str | Path | Mapping[str, str | Path]
+
+
+# `page_react_html()` tags the `ui.page_html()` document it returns with the
+# directory it was read from, so `ReactApp` can serve the sibling assets
+# (`ui.js` etc.) the document references. An attribute rather than a subclass:
+# py-shiny exports `ui.page_html()` but not its document class.
+SRC_DIR_ATTR = "_shinyreact_src_dir"
+
+
+def _add_react_dir(
+    static_assets: StaticAssets | None | MISSING_TYPE, react_dir: Path | None
+) -> StaticAssets | None:
+    """Resolve ``static_assets`` into what :class:`shiny.App` should mount.
+
+    ``react_dir`` is the directory a full HTML document's relative asset URLs
+    resolve against, so it has to be served at ``"/"``. It is *added to* what
+    the author asked for rather than replacing it, so an unrelated mount cannot
+    silently stop ``ui.js`` from being served. Four cases:
+
+    - not passed (``MISSING``) → ``react_dir`` at ``"/"``
+    - ``None`` → nothing; the author said no static assets and meant it
+    - a mapping → their mounts, plus ``react_dir`` at ``"/"`` if they left
+      ``"/"`` free
+    - a bare path → theirs only; a bare path *is* the ``"/"`` mount, so they
+      have already said which directory serves the document's siblings
+    """
+    author_mounts: Mapping[str, str | Path]
+    if isinstance(static_assets, MISSING_TYPE):
+        author_mounts = {}
+    elif static_assets is None or not isinstance(static_assets, Mapping):
+        return static_assets
+    else:
+        author_mounts = static_assets
+
+    if react_dir is None or not react_dir.is_dir():
+        return author_mounts or None
+    # Author's keys last, so an explicit "/" replaces ours. Shiny sorts mount
+    # points by descending length itself, so insertion order is irrelevant.
+    return {"/": react_dir, **author_mounts}
+
+
+class ReactApp(_ShinyApp):
+    """:class:`shiny.App` for the ui.tsx pattern — the UI is discovered.
+
+    The app file is just the server::
+
+        from shinyreact import ReactApp
+
+        app = ReactApp(server, bookmark_store="url")
+
+    With no ``ui=``, the UI is discovered next to the calling module the same
+    way :func:`set_react_page` discovers it: ``www/index.html`` present →
+    :func:`page_react_html`; otherwise → :func:`page_react` (``www/ui.js`` /
+    ``www/ui.css``, served by the dependency itself). The discovered UI is a
+    function of the request, so it re-renders per request — which is what makes
+    ``bookmark_store=`` work with no further wiring, and what lets the mode
+    switch mid-session when you create or delete ``www/index.html``.
+
+    ``ui=`` overrides discovery and behaves exactly like ``shiny.App``'s ``ui``
+    argument, except that a document from :func:`page_react_html` still gets
+    its directory mounted. Note the
+    discovery reads the *immediate* calling frame (like :func:`page_react_dep`),
+    so a helper that wraps ``ReactApp(...)`` must pass ``ui=`` explicitly.
+
+    Args:
+        server: The server function, as for :class:`shiny.App`.
+        ui: Overrides UI discovery. Anything ``shiny.App`` accepts.
+        static_assets: Extra static mounts. **Added to** the React asset
+            directory rather than replacing it — see below. Defaults to
+            :data:`shiny.types.MISSING`, not ``None``, so that passing ``None``
+            explicitly can mean "no static assets at all".
+        bookmark_store: ``"url"`` / ``"server"`` to enable bookmarking, as for
+            :class:`shiny.App`. Requires a callable UI, which discovery
+            provides; a static ``ui=page_react_html(...)`` raises.
+        shinyreact_js: Who supplies ``shinyreact.js`` / ``shinyreact.css`` to
+            the discovered UI: ``"server"`` (default) or ``"client"`` for an
+            npm-tier app whose bundle imports ``@posit-dev/shinyreact``. Ignored
+            when ``ui=`` is passed — build that UI with
+            ``shinyreact_js="client"`` yourself.
+        **kwargs: Forwarded to :class:`shiny.App` (``debug=``, ``test_mode=``).
+
+    Static assets
+    -------------
+    A full HTML document references its bundle with a plain relative URL
+    (``<script src="ui.js">``), so *something* has to serve the directory the
+    document lives in. ``ReactApp`` mounts it at ``/`` for you:
+
+    - **discovery mode** — ``www/`` next to the app file, mounted whenever the
+      directory exists. It is mounted even in ``page_react()`` mode, where the
+      dependency serves the assets itself and the mount is unused: the mode is
+      decided per *request* while ``static_assets`` is a *constructor*
+      argument, so an unused mount is the only way to keep both modes working.
+      An unused mount is harmless; a missing one is a 404 per asset.
+    - **``ui=page_react_html(...)``** — the document's own directory, which
+      :func:`page_react_html` tagged onto the document it returned.
+
+    Your ``static_assets`` is **merged with** that mount, not substituted for
+    it, so adding an unrelated mount doesn't take the bundle down with it::
+
+        ReactApp(server, static_assets={"/data": DATA_DIR})
+        # serves /data from DATA_DIR *and* / from www/
+
+    You win wherever you actually collide with it, and there are three ways to::
+
+        ReactApp(server, static_assets={"/": DIST_DIR})  # explicit "/" key
+        ReactApp(server, static_assets=DIST_DIR)         # a bare path *is* "/"
+        ReactApp(server, static_assets=None)             # nothing mounted
+
+    The last one is why the default is :data:`shiny.types.MISSING` rather than
+    ``None``: with ``None`` as the default there would be no way to say "mount
+    nothing", since not passing the argument and passing ``None`` would look
+    identical from in here.
+
+    Shiny requires every mount path to be absolute, and sorts mount points by
+    descending length, so a nested mount is matched before ``/``.
+    """
+
+    def __init__(
+        self,
+        server: Any,
+        *,
+        ui: Any = None,
+        static_assets: StaticAssets | None | MISSING_TYPE = MISSING,
+        bookmark_store: Literal["url", "server", "disable"] = "disable",
+        shinyreact_js: ShinyreactJs = "server",
+        **kwargs: Any,
+    ) -> None:
+        # Validate now rather than at first page render: a typo should fail at
+        # startup, next to the call that made it.
+        _serves_bundle(shinyreact_js)
+
+        # The directory holding the React bundle, to be mounted at "/".
+        react_dir: Path | None = None
+
+        if ui is None:
+            # Import here: _page imports SRC_DIR_ATTR from this module.
+            from ._page import page_react, page_react_html
+
+            caller_file = sys._getframe(1).f_globals.get("__file__")
+            # No __file__ (REPL / exec'd code): fall back to CWD, matching
+            # page_react() / page_react_html().
+            app_dir = Path(caller_file).parent if caller_file else Path.cwd()
+            src_dir = app_dir / "www"
+            index_path = src_dir / "index.html"
+            react_dir = src_dir
+
+            def discovered_ui(request: Any) -> Any:
+                # Re-checked per request, not latched at construction: the UI is
+                # already a per-request function, so creating or deleting
+                # www/index.html during a dev session now switches modes without
+                # a restart. `exists()` is one stat call per page render.
+                if index_path.exists():
+                    return page_react_html(index_path, shinyreact_js=shinyreact_js)
+                return page_react(src_dir=src_dir, shinyreact_js=shinyreact_js)
+
+            ui = discovered_ui
+
+        else:
+            react_dir = getattr(ui, SRC_DIR_ATTR, None)
+
+            if react_dir is not None and bookmark_store != "disable":
+                # Shiny would raise here too ("App(ui=) must be a function"),
+                # but the fix a shinyreact author needs is specific, and the
+                # obvious workaround is wrong: wrapping *this object* in a
+                # `lambda request: doc` yields a callable UI that never
+                # restores, because page_react_html() reads the RestoreContext
+                # when it builds the config tag — i.e. already, before any
+                # request. The call has to happen per request.
+                raise TypeError(
+                    "bookmark_store= needs a UI that is rebuilt per request, but"
+                    " ui=page_react_html(...) is a single document built once."
+                    " Drop ui= and let ReactApp discover www/index.html, or pass"
+                    " the call itself:"
+                    ' ui=lambda request: page_react_html("client/index.html").'
+                )
+
+        super().__init__(
+            ui,
+            server,
+            static_assets=_add_react_dir(static_assets, react_dir),
+            bookmark_store=bookmark_store,
+            **kwargs,
+        )

shinyreact/_bookmark.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+
+from htmltools import HTML, HTMLDependency, head_content, tags
+from shiny.bookmark._restore_state import (
+    RestoreContext,
+    get_current_restore_context,
+)
+
+from ._protocol import PROTOCOL_VERSION
+
+
+def _read_restore_input_values(ctx: RestoreContext) -> dict[str, object]:
+    """Return the underlying input value map from a RestoreContext.
+
+    Reads ``ctx.input.as_dict()`` directly. Does NOT call ``RestoreInputSet.get()``
+    or the public ``restore_input(id, default)`` helper — those mark each value
+    as pending and Shiny's normal flow would mark them used on the first flush,
+    making the value unavailable to subsequent ``restore_input`` callers in the
+    same render. We only want to *report* the values to the client; consumption
+    semantics are unchanged.
+    """
+    return ctx.input.as_dict()
+
+
+def _current_restore_values() -> dict[str, object]:
+    """Restored input values for the active request, or {} when none.
+
+    Returns ``{}`` when no session/RestoreContext is active (outside an HTTP
+    request) or when no bookmark query string was parsed.
+    """
+    try:
+        ctx = get_current_restore_context()
+    except RuntimeError:
+        # No active session/RestoreContext available outside an HTTP request.
+        return {}
+    if ctx is None:
+        return {}
+    return _read_restore_input_values(ctx)
+
+
+def _config_script_tag() -> HTMLDependency:
+    """Head-injected ``#shinyreact-config`` JSON script tag.
+
+    Always emitted by page entry points. Carries the wire-protocol version
+    (asserted by the JS client at boot — see
+    ``decisions/2026-08-17-js-distribution.md``) and, when a bookmark is being
+    restored, the restored input values under ``restore``.
+
+    The payload is plain JSON in a ``type="application/json"`` script tag —
+    the browser never executes it as JavaScript, so no JS-string-literal
+    escaping is needed. Exactly one property of the encoding matters:
+
+    - Every ``<`` is emitted as ``\\u003c`` so the payload can never contain
+      ``</script`` (which would terminate the surrounding tag) or ``<!--``.
+
+    ``json.dumps`` also defaults to ``ensure_ascii=True``, so non-ASCII lands
+    as ``\\uXXXX`` escapes — but nothing depends on that. U+2028 / U+2029 were
+    a hazard only while the payload was a JS string literal (#183); inside a
+    JSON tag they are inert, which is why R emits them literally and the tests
+    in both languages assert a *round-trip* rather than an escape.
+
+    The client reads it with ``JSON.parse``, which treats keys like
+    ``__proto__`` and ``constructor`` as ordinary own properties.
+
+    SECURITY
+    --------
+    Bookmarked input values appear in the rendered HTML page source. In
+    URL bookmark mode the values are also already in the URL itself, so this
+    tag adds no exposure. In server-stored bookmark mode (``?_state_id_=...``)
+    the URL hides the values, but this tag re-exposes them in the page
+    source. Anything that can read the HTML — browser extensions, logging
+    proxies, screen captures, "View Source" — can read these values. Apps must
+    not put credentials, tokens, PII, or other sensitive data into inputs that
+    participate in bookmarking.
+    """
+    config: dict[str, object] = {"protocolVersion": PROTOCOL_VERSION}
+    values = _current_restore_values()
+    if values:
+        config["restore"] = values
+
+    payload = json.dumps(config).replace("<", "\\u003c")
+    return head_content(
+        tags.script(HTML(payload), type="application/json", id="shinyreact-config")
+    )

shinyreact/_dep.py

@@ -0,0 +1,93 @@
+from pathlib import Path
+from typing import Literal
+
+from htmltools import HTMLDependency, TagChild, TagList
+
+from ._bookmark import _config_script_tag
+
+_WWW_DIR = Path(__file__).parent / "www"
+
+# `@posit-dev/shinyreact`'s version, i.e. the release of the bundle in `www/`.
+# It is the shinyreact HTMLDependency's version, so
+# `/lib/shinyreact-0.1.1/shinyreact.js` names the JS release being served and
+# an npm-tier app can read the page source to see whether its bundled copy
+# matches the server's. Bump alongside `pkg-js/package.json`; `test_dep.py`
+# pins the two together. Mirrors R's `.shinyreact_js_version`.
+_SHINYREACT_JS_VERSION = "0.1.1"
+
+# Only reachable from a repo checkout (editable install), never from an
+# installed wheel. Its presence is the "dev checkout" signal for
+# `_bundle_version()`.
+_JS_PACKAGE_JSON = Path(__file__).parents[3] / "pkg-js" / "package.json"
+
+# Who supplies shinyreact.js (and shinyreact.css) to the page.
+ShinyreactJs = Literal["server", "client"]
+_SHINYREACT_JS_VALUES = ("server", "client")
+
+
+def _file_mtime_int(path: Path) -> int | None:
+    """Return the file's mtime in whole seconds, or None if it doesn't exist."""
+    try:
+        return int(path.stat().st_mtime)
+    except FileNotFoundError:
+        return None
+
+
+def _bundle_version() -> str:
+    """``_SHINYREACT_JS_VERSION``, suffixed with the bundle's mtime in a dev checkout.
+
+    An installed package serves ``/lib/shinyreact-0.1.1/``. In the repo
+    checkout it is ``/lib/shinyreact-0.1.1.<mtime>/`` instead, so a
+    ``make update-dist`` still cache-busts while the URL still names the release.
+    Mirrors R's ``.bundle_version()``.
+    """
+    if _JS_PACKAGE_JSON.is_file():
+        mtime = _file_mtime_int(_WWW_DIR / "shinyreact.js")
+        if mtime is not None:
+            return f"{_SHINYREACT_JS_VERSION}.{mtime}"
+    return _SHINYREACT_JS_VERSION
+
+
+def _dep() -> HTMLDependency:
+    return HTMLDependency(
+        name="shinyreact",
+        version=_bundle_version(),
+        source={"subdir": str(_WWW_DIR)},
+        script={"src": "shinyreact.js", "defer": ""},
+        stylesheet={"href": "shinyreact.css"},
+    )
+
+
+def _serves_bundle(shinyreact_js: ShinyreactJs) -> bool:
+    """Validate ``shinyreact_js=`` and say whether the page attaches the bundle.
+
+    The one place the value is checked, so every entry point rejects a typo the
+    same way. A bad value is a startup error rather than a page that silently
+    loads no hooks.
+    """
+    if shinyreact_js not in _SHINYREACT_JS_VALUES:
+        expected = ", ".join(repr(v) for v in _SHINYREACT_JS_VALUES)
+        raise ValueError(
+            f"shinyreact_js={shinyreact_js!r} is not valid. Expected one of "
+            f'{expected}. Use "server" when the shinyreact package should serve '
+            "shinyreact.js (the default, and what a no-build app needs), and "
+            '"client" when your own bundle imports @posit-dev/shinyreact and '
+            "therefore ships its own copy."
+        )
+    return shinyreact_js == "server"
+
+
+def _dep_page(shinyreact_js: ShinyreactJs = "server") -> TagChild:
+    """Page-level shinyreact dependency: bundle + ``#shinyreact-config`` tag.
+
+    Use from page entry points (``page_react_html``, ``set_react_page``'s page
+    function) — the config tag carries the protocol version on every page and
+    the bookmark restore payload when one is active.
+
+    ``shinyreact_js="client"`` omits ``shinyreact.js`` / ``shinyreact.css`` for
+    npm-tier pages, whose client bundle ships its own copy. The config tag is
+    always emitted: it carries the protocol version and any bookmark restore
+    payload.
+    """
+    bundle = _dep() if _serves_bundle(shinyreact_js) else None
+    return TagList(bundle, _config_script_tag())

shinyreact/_dep_discovery.py

@@ -0,0 +1,76 @@
+"""Automatic renderer HTML-dependency discovery for Core mode (#146, #203, #220).
+
+Express's ``set_react_page()`` can inline renderer dependencies into the page
+head because the page function runs after the renderers mount. A Core-mode page
+(:func:`page_react`, :func:`page_react_html`) is built before ``server()`` runs,
+so there is nothing to inline. Instead — the same design R uses
+(``pkg-r/R/dep-discovery.R``) — after every reactive flush we diff the session's
+registered outputs, extract each new output's UI, and push any not-yet-sent
+dependencies to the client as a ``shinyreact-deps`` custom message. The JS
+bundle loads them and re-runs ``Shiny.bindAll()``.
+
+Diffing on *every* flush (not just the first) also covers outputs registered
+after startup — e.g. a module server mounted inside an observer.
+
+The hook: the JS bundle sends one ``.shinyreact_init`` ping (type
+``shinyreact.init``) after Shiny initializes; that type's input handler
+(``_input_handler.py``) calls :func:`install_dep_discovery`. Every session gets
+exactly one ping, whether or not the app has any other inputs.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from htmltools import HTMLDependency, Tag, TagList
+
+if TYPE_CHECKING:
+    from shiny.session import Session
+
+_INSTALLED_FLAG = "_shinyreact_dep_discovery"
+
+
+def install_dep_discovery(session: Session | None) -> bool:
+    """Install the per-session flush hook. Returns whether it was installed."""
+    if session is None:
+        return False
+    # `_outputs` and `on_flushed` are missing on mock/express-stub sessions;
+    # discovery no-ops there rather than raising.
+    outputs = getattr(getattr(session, "output", None), "_outputs", None)
+    if outputs is None or not callable(getattr(session, "on_flushed", None)):
+        return False
+    # Two copies of the JS bundle on one page send two pings; install once.
+    # (py-shiny has no `session$userData` equivalent, so: an attribute.)
+    if getattr(session, _INSTALLED_FLAG, False):
+        return False
+    setattr(session, _INSTALLED_FLAG, True)
+
+    seen_outputs: set[str] = set()
+    sent_deps: set[str] = set()
+
+    async def push_new_output_deps() -> None:
+        new_names = [name for name in outputs if name not in seen_outputs]
+        if not new_names:
+            return
+        seen_outputs.update(new_names)
+
+        deps: list[HTMLDependency] = []
+        for name in new_names:
+            ui = outputs[name].renderer.auto_output_ui()
+            if isinstance(ui, (Tag, TagList)):
+                deps.extend(ui.tagify().get_dependencies())
+        deps = [d for d in deps if f"{d.name}@{d.version}" not in sent_deps]
+        if not deps:
+            return
+        sent_deps.update(f"{d.name}@{d.version}" for d in deps)
+
+        # `_process_ui()` registers each dep's resource route with the app and
+        # returns the client-side JSON (Python's `createWebDependency()`). The
+        # client skips deps already on the page, so overlap is harmless.
+        payload = session._process_ui(TagList(*deps))["deps"]
+        await session.send_custom_message(
+            "shinyreact-deps", cast("dict[str, object]", payload)
+        )
+
+    session.on_flushed(cast(Any, push_new_output_deps), once=False)
+    return True

shinyreact/_input_handler.py

@@ -0,0 +1,42 @@
+"""Built-in shinyreact input handlers, registered on import.
+
+See docs/superpowers/specs/2026-06-04-shinyreact-default-input-handler-design.md.
+
+Python's deserializer never simplifies the way R's does (an array of objects is
+already a list of dicts), so both handlers are no-ops here. They exist so that
+the ``:shinyreact.default`` / ``:shinyreact.asis`` wire suffixes do not raise
+"No input handler registered for type" on the Python server.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from shiny.input_handler import input_handlers
+
+from ._dep_discovery import install_dep_discovery
+
+if TYPE_CHECKING:
+    from shiny.module import ResolvedId
+    from shiny.session import Session
+
+
+# force=True so re-importing this module (e.g. importlib.reload during dev or
+# tests) re-registers idempotently instead of raising "already registered".
+@input_handlers.add("shinyreact.default", force=True)
+def _shinyreact_default(value: Any, name: ResolvedId, session: Session) -> Any:
+    return value
+
+
+@input_handlers.add("shinyreact.asis", force=True)
+def _shinyreact_asis(value: Any, name: ResolvedId, session: Session) -> Any:
+    return value
+
+
+# The JS bundle sends one `.shinyreact_init:shinyreact.init` ping per session
+# after Shiny initializes (pkg-js/src/dep-discovery.ts); the handler bootstraps
+# automatic output dependency discovery, matching R (issue #220).
+@input_handlers.add("shinyreact.init", force=True)
+def _shinyreact_init(value: Any, name: ResolvedId, session: Session) -> Any:
+    install_dep_discovery(session)
+    return value