Allow defining custom JS modules

Archmonger · Archmonger · commit dd7179cacffa · 2024-06-22T03:16:54.000-07:00
diff --git a/docs/examples/html/pyscript-js-module.html b/docs/examples/html/pyscript-js-module.html
@@ -0,0 +1,14 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup extra_js='{"/static/moment.js":"moment"}' %}
+</head>
+
+<body>
+    {% component "example_project.my_app.components.root.py" %}
+</body>
+
+</html>
diff --git a/docs/examples/html/pyscript-setup-config-string.html b/docs/examples/html/pyscript-setup-config-string.html
@@ -1,4 +1,4 @@
 <head>
     <title>ReactPy</title>
-    {% pyscript_setup config="{'experimental_create_proxy':'auto'}" %}
+    {% pyscript_setup config='{"experimental_create_proxy":"auto"}' %}
 </head>
diff --git a/docs/examples/html/pyscript-setup-extra-js-object.html b/docs/examples/html/pyscript-setup-extra-js-object.html
@@ -0,0 +1,14 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup extra_js=my_extra_js_object %}
+</head>
+
+<body>
+    {% component "example_project.my_app.components.root.py" %}
+</body>
+
+</html>
diff --git a/docs/examples/html/pyscript-setup-extra-js-string.html b/docs/examples/html/pyscript-setup-extra-js-string.html
@@ -0,0 +1,14 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup extra_js='{"/static/moment.js":"moment"}' %}
+</head>
+
+<body>
+    {% component "example_project.my_app.components.root.py" %}
+</body>
+
+</html>
diff --git a/docs/examples/python/pyscript-js-module.py b/docs/examples/python/pyscript-js-module.py
@@ -0,0 +1,12 @@
+from reactpy import component, html
+
+
+@component
+def root():
+    from pyscript.js_modules import moment
+
+    return html.div(
+        {"id": "moment"},
+        "Using the JavaScript package 'moment' to calculate time: ",
+        moment.default().format("YYYY-MM-DD HH:mm:ss"),
+    )
diff --git a/docs/examples/python/pyscript-setup-extra-js-object.py b/docs/examples/python/pyscript-setup-extra-js-object.py
@@ -0,0 +1,10 @@
+from django.shortcuts import render
+from django.templatetags.static import static
+
+
+def index(request):
+    return render(
+        request,
+        "my_template.html",
+        context={"my_extra_js_object": {static("moment.js"): "moment"}},
+    )
diff --git a/docs/src/reference/template-tag.md b/docs/src/reference/template-tag.md
@@ -195,16 +195,30 @@ Your PyScript component file requires a `#!python def root()` component to funct
 
 ??? question "How do I execute JavaScript within PyScript components?"
 
-    PyScript components have the ability to directly execute JavaScript using the [`pyodide` `js` module](https://pyodide.org/en/stable/usage/type-conversions.html#importing-javascript-objects-into-python) or [`pyscript` foreign function interface](https://docs.pyscript.net/2024.6.1/user-guide/dom/).
+    PyScript components have the ability to directly execute standard library JavaScript using the [`pyodide` `js` module](https://pyodide.org/en/stable/usage/type-conversions.html#importing-javascript-objects-into-python) or [`pyscript` foreign function interface](https://docs.pyscript.net/2024.6.1/user-guide/dom/).
 
-    _The `#!python js` module has access to everything within the browser's JavaScript environment. Therefore, any public JavaScript functions loaded within your HTML `#!html <head>` can be called as well. However, be mindful of JavaScript load order!_
+    The `#!python js` module has access to everything within the browser's JavaScript environment. Therefore, any global JavaScript functions loaded within your HTML `#!html <head>` can be called as well. However, be mindful of JavaScript load order!
 
     === "root.py"
 
         ```python
         {% include "../../examples/python/pyscript-js-execution.py" %}
         ```
 
+    To import JavaScript modules in a fashion similar to `#!javascript import {moment} from 'static/moment.js'`, you will need to configure your `#!jinja {% pyscript_setup %}` block to make the module available to PyScript. This module will be accessed within `#!python pyscript.js_modules.*`. For more information, see the [PyScript JS modules docs](https://docs.pyscript.net/2024.6.2/user-guide/configuration/#javascript-modules).
+
+    === "root.py"
+
+        ```python
+        {% include "../../examples/python/pyscript-js-module.py" %}
+        ```
+
+    === "my_template.html"
+
+        ```jinja
+        {% include "../../examples/html/pyscript-js-module.html" %}
+        ```
+
 <!--pyscript-js-exec-end-->
 
 <!--pyscript-multifile-start-->
@@ -297,12 +311,13 @@ You can optionally include a list of Python packages to install within the PyScr
 
     | Name | Type | Description | Default |
     | --- | --- | --- | --- |
-    | `#!python *dependencies` | `#!python str` | Dependencies that need to be loaded on the page for your PyScript components. Each dependency must be contained within it's own string and written in Python requirements file syntax. | N/A |
+    | `#!python *extra_py` | `#!python str` | Dependencies that need to be loaded on the page for your PyScript components. Each dependency must be contained within it's own string and written in Python requirements file syntax. | N/A |
+    | `#!python extra_js` | `#!python str | dict` | A JSON string or Python dictionary containing a vanilla JavaScript module URL and the `#!python name: str` to access it within `#!python pyscript.js_modules.*`. | `#!python ""` |
     | `#!python config` | `#!python str | dict` | A JSON string or Python dictionary containing PyScript configuration values. | `#!python ""` |
 
-??? question "How do I define dependencies for my PyScript component?"
+??? question "How do I install additional Python dependencies?"
 
-    Dependencies must be available on [`pypi`](https://pypi.org/), written in pure Python, and declared in your `#!jinja {% pyscript_setup %}` block using Python requirements file syntax.
+    Dependencies must be available on [`pypi`](https://pypi.org/) and declared in your `#!jinja {% pyscript_setup %}` block using Python requirements file syntax.
 
     These dependencies are automatically downloaded and installed into the PyScript client-side environment when the page is loaded.
 
@@ -312,6 +327,30 @@ You can optionally include a list of Python packages to install within the PyScr
         {% include "../../examples/html/pyscript-setup-dependencies.html" %}
         ```
 
+??? question "How do I install additional Javascript dependencies?"
+
+    You can use the `#!python extra_js` keyword to load additional JavaScript modules into your PyScript environment.
+
+    === "my_template.html"
+
+        ```jinja
+        {% include "../../examples/html/pyscript-setup-extra-js-object.html" %}
+        ```
+
+    === "views.py"
+
+        ```python
+        {% include "../../examples/python/pyscript-setup-extra-js-object.py" %}
+        ```
+
+    The value for `#!python extra_js` is most commonly a Python dictionary, but JSON strings are also supported.
+
+    === "my_template.html"
+
+        ```jinja
+        {% include "../../examples/html/pyscript-setup-extra-js-string.html" %}
+        ```
+
 ??? question "How do I modify the `pyscript` default configuration?"
 
     You can modify the default [PyScript configuration](https://docs.pyscript.net/2024.6.2/user-guide/configuration/) by providing a value to the `#!python config` keyword.
diff --git a/src/reactpy_django/templatetags/reactpy.py b/src/reactpy_django/templatetags/reactpy.py
@@ -217,21 +217,25 @@ def pyscript_component(
 
 @register.inclusion_tag("reactpy/pyscript_setup.html")
 def pyscript_setup(
-    *dependencies: str,
+    *extra_py: str,
+    extra_js: str | dict = "",
     config: str | dict = "",
 ):
     """
     Args:
-        dependencies: Dependencies that need to be loaded on the page for \
+        extra_py: Dependencies that need to be loaded on the page for \
             your PyScript components. Each dependency must be contained \
             within it's own string and written in Python requirements file syntax.
     
     Kwargs:
+        extra_js: A JSON string or Python dictionary containing a vanilla \
+            JavaScript module URL and the `name: str` to access it within \
+            `pyscript.js_modules.*`. 
         config: A JSON string or Python dictionary containing PyScript \
             configuration values.
     """
     return {
-        "pyscript_config": extend_pyscript_config(config, dependencies),
+        "pyscript_config": extend_pyscript_config(extra_py, extra_js, config),
         "pyscript_layout_handler": PYSCRIPT_LAYOUT_HANDLER,
         "reactpy_debug_mode": reactpy_config.REACTPY_DEBUG_MODE,
     }
diff --git a/src/reactpy_django/utils.py b/src/reactpy_django/utils.py
@@ -2,6 +2,7 @@
 
 import contextlib
 import inspect
+import json
 import logging
 import os
 import re
@@ -496,10 +497,12 @@ def render_pyscript_template(file_paths: Sequence[str], uuid: str, root: str):
     return executor.replace("    def root(): ...", user_code)
 
 
-def extend_pyscript_config(config: dict | str, extra_packages: Sequence) -> str:
+def extend_pyscript_config(
+    extra_py: Sequence, extra_js: dict | str, config: dict | str
+) -> str:
     """Extends ReactPy's default PyScript config with user provided values."""
+    # Lazily set up the initial config in to wait for Django's static file system
     if not PYSCRIPT_DEFAULT_CONFIG:
-        # Need to perform this lazily in order to wait for static files to be available
         PYSCRIPT_DEFAULT_CONFIG.update(
             {
                 "packages": [
@@ -514,11 +517,21 @@ def extend_pyscript_config(config: dict | str, extra_packages: Sequence) -> str:
                 },
             }
         )
+
+    # Extend the Python dependency list
     pyscript_config = deepcopy(PYSCRIPT_DEFAULT_CONFIG)
-    pyscript_config["packages"].extend(extra_packages)
+    pyscript_config["packages"].extend(extra_py)
+
+    # Extend the JavaScript dependency list
+    if extra_js and isinstance(extra_js, str):
+        pyscript_config["js_modules"]["main"].update(json.loads(extra_js))
+    elif extra_js and isinstance(extra_js, dict):
+        pyscript_config["js_modules"]["main"].update(extra_py)
+
+    # Update the config
     if config and isinstance(config, str):
-        pyscript_config.update(orjson.loads(config))
-    elif isinstance(config, dict):
+        pyscript_config.update(json.loads(config))
+    elif config and isinstance(config, dict):
         pyscript_config.update(config)
     return orjson.dumps(pyscript_config).decode("utf-8")
 
diff --git a/tests/test_app/pyscript/components/remote_js_module.py b/tests/test_app/pyscript/components/remote_js_module.py
@@ -0,0 +1,14 @@
+from reactpy import component, html
+
+
+@component
+def root():
+    from pyscript.js_modules import moment
+
+    time: str = moment.default().format("YYYY-MM-DD HH:mm:ss")
+
+    return html.div(
+        {"id": "moment", "data-success": bool(time)},
+        "Using the JavaScript package 'moment' to calculate time: ",
+        time,
+    )
diff --git a/tests/test_app/static/moment.js b/tests/test_app/static/moment.js
diff --git a/tests/test_app/templates/pyscript.html b/tests/test_app/templates/pyscript.html
diff --git a/tests/test_app/tests/test_components.py b/tests/test_app/tests/test_components.py
