Current Situation

idom.run() probably shouldn't be the primary advertised way of using IDOM. Especially in it's current state.

Using a development webserver for production use is a big no-no, and by prominently displaying idom.run() as the first steps to using IDOM shows we are encouraging people to do just that. I believe the primary way of utilizing IDOM should be embedding within existing applications.

• #654

Proposed Actions

• [ ] Keep idom.run() as is, but add logging to indicate idom.run() is not suited for production use.
  • ex. idom.run() is only intended for testing purposes. For production use, consider embedding IDOM within an existing project. Check out the docs for more info.
• [ ] Expand the ease-of-use for integrating into supported web frameworks, similar to Django-IDOM
  • #653
• [ ] Remove SharedClientState, as it is not compatible with multiprocessed webservers.
  • This is also an opportunity to rename PerClientState to IdomView

Optional

• Change the callable name/path to more appropriately indicate danger or for testing purposes only
  • idom.testing.webserver()
  • idom.shortcuts.run()
  • idom.devtools.run_webserver()
• Remove the pip parameter for frameworks (it's really not needed)
  • idom.run() should raise a simple to understand exception if the user has forgotten to install a web framework
  • ex. Looks like you don't have a web framework installed. You'll need to pip install one of the following: fastapi, flask, sanic

This pull request is provisional, and it may never be merged. Hopefully it can serve as a useful reference if this is asked about in the future.

What This Does

This PR allows you to define components using classes similarly to how you would in React. Python's __setattr__ magic method makes it a bit easier to implement though since you no longer need an update method. Instead the instance attributes can be assigned directly.

@idom.component
class Counter:
    def __init__(self, count: int = 0):
        self.initial_count = self.count = count

    def render(self):
        return idom.html.div(
            f"Count: {self.count}",
            idom.html.button({"onClick": self.reset}, "Reset"),
            idom.html.button({"onClick": self.increment}, "+"),
            idom.html.button({"onClick": self.decrement}, "-"),
        )

    def increment(self, event):
        self.count += 1

    def decrement(self, event):
        self.count -= 1

    def reset(self, event):
        self.count = self.initial_count

Limitations

This PR does not allow class-based components to incur side effects. We may leave that as an intentional limitation though in order to try and push people towards functional components because they encourage better patterns of development.

Disadvantages

1. Having two ways to do the same thing might be confusing. Do we introduce class-based or function-based components first?
2. Class-based components are less composable and can encourage anti-patterns - most new React libraries use hooks for this reason.
3. It will likely be strange for users to see that mutating attributes of their components will not trigger updates. For example, appending to a list won't trigger a re-render.
4. It probably isn't that big of a deal, but I suspect these class-based components might be less performant - users would have to understand that every attribute assignment has side effects they may not be aware of.

Advantages

• If used sparingly, class-based components could enable some useful imperative interfaces. This would probably be a bad use case, but in the Counter example above a parent component could increment the count by mutating its attributes.
• Class based components could serve as a useful introduction to the execution model. The idea being that we avoid scaring off new users, but intentionally limit class-based capabilities in order to push them towards learning/using function-based ones.

This PR aims to re-organize existing documentation as well as create an outline for new documentation.

closes: #512, #442, #444, #445, #447, #448, #449

Current Situation

This error periodically shows client side and will completely break IDOM, but seems to fix itself if clearing browser cache. Something notable is I have never seen this issue when Django-IDOM was using idom==0.33.0, but that may just be coincidence.

This is the exception stack shown in browser console.

react-dom.js:8 Error: Minified React error #321; visit https://reactjs.org/docs/error-decoder.html?invariant=321 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
    at a (react.js:2:4779)
    at n.useState (react.js:2:6903)
    at react-bootstrap.js:2:44831
    at ql (react-dom.js:6:52870)
    at Uu (react-dom.js:6:60908)
    at gs (react-dom.js:10:10631)
    at ms (react-dom.js:10:933)
    at pf (react-dom.js:10:864)
    at Et (react-dom.js:10:724)
    at xi (react-dom.js:8:10854)
ai @ react-dom.js:8
react-dom.js:10 Uncaught Error: Minified React error #321; visit https://reactjs.org/docs/error-decoder.html?invariant=321 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
    at a (react.js:2:4779)
    at n.useState (react.js:2:6903)
    at react-bootstrap.js:2:44831
    at ql (react-dom.js:6:52870)
    at Uu (react-dom.js:6:60908)
    at gs (react-dom.js:10:10631)
    at ms (react-dom.js:10:933)
    at pf (react-dom.js:10:864)
    at Et (react-dom.js:10:724)
    at xi (react-dom.js:8:10854)
client.js:23649 The above error occurred in the <_ImportedElement> component:

    at _ImportedElement (http://127.0.0.1:7575/static/django_idom/client.js:31103:29)
    at ImportedElement (http://127.0.0.1:7575/static/django_idom/client.js:31075:28)
    at Element (http://127.0.0.1:7575/static/django_idom/client.js:31046:20)
    at div
    at StandardElement (http://127.0.0.1:7575/static/django_idom/client.js:31060:28)
    at Element (http://127.0.0.1:7575/static/django_idom/client.js:31046:20)
    at Layout (http://127.0.0.1:7575/static/django_idom/client.js:31034:19)

Consider adding an error boundary to your tree to customize error handling behavior.
Visit https://reactjs.org/link/error-boundaries to learn more about error boundaries.
logCapturedError @ client.js:23649
client.js:2691 Uncaught Error: Minified React error #321; visit https://reactjs.org/docs/error-decoder.html?invariant=321 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
    at a (react.js:2:4779)
    at n.useState (react.js:2:6903)
    at react-bootstrap.js:2:44831
    at ql (react-dom.js:6:52870)
    at Uu (react-dom.js:6:60908)
    at gs (react-dom.js:10:10631)
    at ms (react-dom.js:10:933)
    at pf (react-dom.js:10:864)
    at Et (react-dom.js:10:724)
    at xi (react-dom.js:8:10854)

Proposed Actions

Determine root cause and develop a solution.

I seem to be semi-frequently able to reproduce this if leaving my webserver running django-idom up while putting my Windows 10 machine to sleep for >12 hours.

See https://github.com/idom-team/idom/discussions/610 for the original discussion.

Work Items

See above.

fix #777

Technical Details

• Generate a DOM tree using lxml
• Recursively converts lxml tree to VDOM
• HTML is encapsulated within a React fragment if needed
• Style tags are handled separately
• Utilize idom.html constructors for VDOM when possible
• Unneeded VDOM fields are pruned after user transformations are applied
• Uses list comprehension where possible for maximum performance

Checklist

Please update this checklist as you complete each item:

• [x] Tests have been included for all bug fixes or added functionality.
• [x] The changelog.rst has been updated with any significant changes.
• [x] GitHub Issues which may be closed by this Pull Request have been linked.

Summary

At the moment WebDriver tests are not run on Windows because they are failing for some unknown reason.

How To Work On This Bug

At the moment WebDriver tests are being skipped. To unskip them when you run the test suite comment out these lines:

https://github.com/idom-team/idom/blob/2804ae2620d4a2b719684460fd56b97deb65b4ba/tests/conftest.py#L151-L161

Current Findings

I don't have a Windows machine myself so it's quite difficult to try and debug. Further the tracebacks and logs that are produced don't really help much in figuring out what the problem is. The only thing I've been able to identify is that not all the files are being loaded from the server when loading up the index.html page.

On Linux (expected behavior):

[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56132]: GET http://localhost:5000/  302 0
[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56132]: GET http://localhost:5000/client/index.html  200 387
[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56132]: GET http://localhost:5000/client/index.js  200 982
[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56132]: GET http://localhost:5000/client/web_modules/idom-client-react.js  200 39291
[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56132]: GET http://localhost:5000/client/web_modules/htm.js  200 1220
[2021-01-29 16:40:55 -0800] - (sanic.access)[INFO][127.0.0.1:56136]: GET http://localhost:5000/client/web_modules/common/index-6ed86a98.js  200 9836

On Windows (missing GET requests):

[2021-01-30 00:32:17 -0000] - (sanic.access)[INFO][127.0.0.1:50486]: GET http://127.0.0.1:50482/  302 0
[2021-01-30 00:32:17 -0000] - (sanic.access)[INFO][127.0.0.1:50486]: GET http://127.0.0.1:50482/client/index.html  200 403
[2021-01-30 00:32:17 -0000] - (sanic.access)[INFO][127.0.0.1:50486]: GET http://127.0.0.1:50482/client/index.js  200 1016

This is odd because index.js should import idom-client-react.js which itself imports other JS files, however the expected requests are missing when running the test suite in CI.

Get Support

I'm happy to help debug this issue with anyone who's interested in investigating.

Current Situation

Currently, onSubmit events for form elements do not serialize the data contained within them. To do this we need to serialize the form.elements attribute.

Proposed Changes

diff --git a/src/client/packages/idom-client-react/src/event-to-object.js b/src/client/packages/idom-client-react/src/event-to-object.js
index b11e653..80b098b 100644
--- a/src/client/packages/idom-client-react/src/event-to-object.js
+++ b/src/client/packages/idom-client-react/src/event-to-object.js
@@ -49,6 +49,13 @@ const elementTransformCategories = {
       return {};
     }
   },
+  hasElements: (element) => {
+    const result = {};
+    for (key in element.elements) {
+      result[key] = serializeDomElement(element.elements[key]);
+    }
+    return result;
+  }
 };
 
 function defaultElementTransform(element) {
@@ -69,6 +76,7 @@ const elementTagCategories = {
   ],
   hasCurrentTime: ["AUDIO", "VIDEO"],
   hasFiles: ["INPUT"],
+  hasElements: ["FORM"],
 };
 
 const elementTransforms = {};

Implementation Details

No response

There's currently some awkwardness in converting django views to VDOM, due to the fact that the head content is never loaded into the page.

For example, CSS/JS that is within <head> is simply never added to the page.

This PR makes html_to_vdom use the same approach browsers use when merging two HTML/body node trees. Namely, the contents of the <head> and <body> tags are directly spit out onto the page, while removing those top level tags themselves.

Checklist

Please update this checklist as you complete each item:

• [X] Tests have been included for all bug fixes or added functionality.
• [x] The changelog.rst has been updated with any significant changes.
• [X] GitHub Issues which may be closed by this Pull Request have been linked.

Bug description

When I try to create a button with material-ui/core it comes out blank and an error is printed in the console: Error: Minified React error #321; visit https://reactjs.org/docs/error-decoder.html?invariant=321 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

The link points to 3 possible causes:

1. You might have mismatching versions of React and the renderer (such as React DOM)
2. You might be breaking the Rules of Hooks
3. You might have more than one copy of React in the same app See https://reactjs.org/link/invalid-hook-call for tips about how to debug and fix this problem.

To reproduce

Run the following Jupyter cell:

import json
import idom_jupyter
import idom

material_ui = idom.install("@material-ui/core", fallback="loading...")

@idom.component
def ViewButtonEvents():
    event, set_event = idom.hooks.use_state(None)

    return idom.html.div(
        material_ui.Button(
            {
                "color": "primary",
                "variant": "contained",
                "onClick": lambda event: set_event(event),
            },
            "Click Me!",
        ),
        idom.html.pre(json.dumps(event, indent=2)),
    )

ViewButtonEvents()

Expected behavior

Expected to see a material-ui button

Additional context

It works fine with the victory example, I see the expected bar chart.

Versions:

• jupyter 1.0.0
• idom 0.22.5
• idom-jupyter 0.5.1

Current Situation

There are a lot of locations in the source & docs where we currently call things "server", when they really should be called "web frameworks"

Proposed Actions

Rename functions, comments, and docs while keeping these guidelines in mind

• Web Framework = FastAPI, Flask, Sanic, Tornado, Django
• Web Server = Gunicorn, Uvicorn, Hypercorn, Daphne, Built-in development servers, etc
• Reactive Component Framework = IDOM
  • It's an easier way to distinguish us rather than the more literal "we are a web framework built on-top of web frameworks"
• Views = Built-ins that assist in plopping something visual onto the page
• Components = We are already pretty good about the usage of "component", no need for change

With idom 0.28.0[stable] a regression was introduced where refreshing the page yields a Error: File not found error. Downgrading to 0.27.0 fixes the issue.

This appears to be resolved in main now, but we should introduce a test to catch this in the future.

Originally posted by @brentbaum in https://github.com/idom-team/idom/discussions/388

Current Situation

If an exception occurs within a script element, all of IDOM breaks.

Proposed Actions

Add error boundaries to prevent the script element from being destructive

Discussed in https://github.com/idom-team/idom/discussions/865

Bumps fast-json-patch from 3.1.0 to 3.1.1.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Current Situation

It is difficult for new contributors to modify the docs, due to the current usage of reStructuredText (RST).

Proposed Actions

Convert the current docs from reStructuredText (sphinx) to Markdown (mkdocs).

Also consider using these plugins

• https://github.com/jimporter/mike for docs versioning
• https://github.com/fralau/mkdocs_macros_plugin for code actions
• https://github.com/greenape/mknotebooks or https://github.com/danielfrg/mkdocs-jupyter for embedding jupyter into the page

Checklist

Please update this checklist as you complete each item:

• [ ] Tests have been included for all bug fixes or added functionality.
• [ ] The changelog.rst has been updated with any significant changes.
• [ ] GitHub Issues which may be closed by this Pull Request have been linked.

Discussed in https://github.com/idom-team/idom/discussions/860