-Ecosystem independence is also a core feature of IDOM. It can be added to existing
-applications built on a variety of sync and async web servers, as well as integrated
-with other frameworks like Django, Jupyter, and Plotly Dash. Not only does this mean
-you're free to choose what technology stack to run on, but on top of that, you can run
-the exact same components wherever you need them. For example, you can take a component
-originally developed in a Jupyter Notebook and embed it in your production application
-without changing anything about the component itself.
+
+[ReactPy](https://reactpy.dev/) is a library for building user interfaces in Python without Javascript. ReactPy interfaces are made from components that look and behave similar to those found in [ReactJS](https://reactjs.org/). Designed with simplicity in mind, ReactPy can be used by those without web development experience while also being powerful enough to grow with your ambitions.
+
+
@@ -58,4 +58,4 @@ def run(self):
def setup(app: Sphinx) -> None:
- app.add_directive("idom-view", IteractiveWidget)
+ app.add_directive("reactpy-view", IteractiveWidget)
diff --git a/docs/source/_static/css/furo-theme-overrides.css b/docs/source/_static/css/furo-theme-overrides.css
index f23c23168..a258e025e 100644
--- a/docs/source/_static/css/furo-theme-overrides.css
+++ b/docs/source/_static/css/furo-theme-overrides.css
@@ -1,4 +1,6 @@
-body {
- --admonition-title-font-size: 1rem !important;
- --admonition-font-size: 1rem !important;
+.sidebar-container {
+ width: 18em;
+}
+.sidebar-brand-text {
+ display: none;
}
diff --git a/docs/source/_static/css/idom-view.css b/docs/source/_static/css/reactpy-view.css
similarity index 91%
rename from docs/source/_static/css/idom-view.css
rename to docs/source/_static/css/reactpy-view.css
index 9abe24198..56df74970 100644
--- a/docs/source/_static/css/idom-view.css
+++ b/docs/source/_static/css/reactpy-view.css
@@ -21,11 +21,6 @@
width: 100%;
}
-.center-content {
- display: flex;
- align-items: center;
- justify-content: center;
-}
.enable-widget-button {
padding: 10px;
color: #ffffff !important;
diff --git a/docs/source/_static/css/set-color-scheme.css b/docs/source/_static/css/set-color-scheme.css
deleted file mode 100644
index 4b9521c7d..000000000
--- a/docs/source/_static/css/set-color-scheme.css
+++ /dev/null
@@ -1,3 +0,0 @@
-:root {
- color-scheme: light dark;
-}
diff --git a/docs/source/_static/css/sphinx-design-overrides.css b/docs/source/_static/css/sphinx-design-overrides.css
index cc9b285c0..767d9d16c 100644
--- a/docs/source/_static/css/sphinx-design-overrides.css
+++ b/docs/source/_static/css/sphinx-design-overrides.css
@@ -1,12 +1,3 @@
-body {
- --sd-color-info: var(--color-admonition-title-background--note);
- --sd-color-warning: var(--color-admonition-title-background--warning);
- --sd-color-danger: var(--color-admonition-title-background--danger);
- --sd-color-info-text: var(--color-admonition-title--note);
- --sd-color-warning-text: var(--color-admonition-title--warning);
- --sd-color-danger-text: var(--color-admonition-title--danger);
-}
-
.sd-card-body {
display: flex;
flex-direction: column;
diff --git a/docs/source/_static/install-and-run-idom.gif b/docs/source/_static/install-and-run-idom.gif
deleted file mode 100644
index 67d226a12..000000000
Binary files a/docs/source/_static/install-and-run-idom.gif and /dev/null differ
diff --git a/docs/source/_static/install-and-run-reactpy.gif b/docs/source/_static/install-and-run-reactpy.gif
new file mode 100644
index 000000000..49d431341
Binary files /dev/null and b/docs/source/_static/install-and-run-reactpy.gif differ
diff --git a/docs/source/about/changelog.rst b/docs/source/about/changelog.rst
new file mode 100644
index 000000000..48a229eee
--- /dev/null
+++ b/docs/source/about/changelog.rst
@@ -0,0 +1,1171 @@
+Changelog
+=========
+
+.. note::
+
+ All notable changes to this project will be recorded in this document. The style of
+ which is based on `Keep a Changelog `__. The versioning
+ scheme for the project adheres to `Semantic Versioning `__. For
+ more info, see the :ref:`Contributor Guide `.
+
+
+.. INSTRUCTIONS FOR CHANGELOG CONTRIBUTORS
+.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+.. If you're adding a changelog entry, be sure to read the "Creating a Changelog Entry"
+.. section of the documentation before doing so for instructions on how to adhere to the
+.. "Keep a Changelog" style guide (https://keepachangelog.com).
+
+Unreleased
+----------
+
+**Fixed**
+
+- :pull:`1118` - `module_from_template` is broken with a recent release of `requests`
+- :pull:`1131` - `module_from_template` did not work when using Flask backend
+- :pull:`1200` - Fixed `UnicodeDecodeError` when using `reactpy.web.export`
+
+**Added**
+
+- :pull:`1165` - Allow asynchronously rendering discrete component tree - enable this
+ experimental feature by setting `REACTPY_ASYNC_RENDERING=true`. This should improve
+ the overall responsiveness of your app, particularly when handling larger renders
+ that would otherwise block faster renders from being processed.
+
+**Changed**
+
+- :pull:`1171` - Previously ``None``, when present in an HTML element, would render as
+ the string ``"None"``. Now ``None`` will not render at all. This is consistent with
+ how ``None`` is handled when returned from components. It also makes it easier to
+ conditionally render elements. For example, previously you would have needed to use a
+ fragment to conditionally render an element by writing
+ ``something if condition else html._()``. Now you can simply write
+ ``something if condition else None``.
+
+**Deprecated**
+
+- :pull:`1171` - The ``Stop`` exception. Recent releases of ``anyio`` have made this
+ exception difficult to use since it now raises an ``ExceptionGroup``. This exception
+ was primarily used for internal testing purposes and so is now deprecated.
+
+
+v1.0.2
+------
+
+**Fixed**
+
+- :issue:`1086` - fix rendering bug when children change positions (via :pull:`1085`)
+
+
+v1.0.1
+------
+
+**Changed**
+
+- :pull:`1050` - Warn and attempt to fix missing mime types, which can result in ``reactpy.run`` not working as expected.
+- :pull:`1051` - Rename ``reactpy.backend.BackendImplementation`` to ``reactpy.backend.BackendType``
+- :pull:`1051` - Allow ``reactpy.run`` to fail in more predictable ways
+
+**Fixed**
+
+- :issue:`930` - better traceback for JSON serialization errors (via :pull:`1008`)
+- :issue:`437` - explain that JS component attributes must be JSON (via :pull:`1008`)
+- :pull:`1051` - Fix ``reactpy.run`` port assignment sometimes attaching to in-use ports on Windows
+- :pull:`1051` - Fix ``reactpy.run`` not recognizing ``fastapi``
+
+
+v1.0.0
+------
+:octicon:`milestone` *released on 2023-03-14*
+
+No changes.
+
+
+v1.0.0-a6
+---------
+:octicon:`milestone` *released on 2023-02-23*
+
+**Fixed**
+
+- :pull:`936` - remaining issues from :pull:`934`
+
+
+v1.0.0-a5
+---------
+:octicon:`milestone` *released on 2023-02-21*
+
+**Fixed**
+
+- :pull:`934` - minor issues with camelCase rewrite CLI utility
+
+
+v1.0.0-a4
+---------
+:octicon:`milestone` *released on 2023-02-21*
+
+**Changed**
+
+- :pull:`919` - Reverts :pull:`841` as per the conclusion in :discussion:`916`. but
+ preserves the ability to declare attributes with snake_case.
+
+**Deprecated**
+
+- :pull:`919` - Declaration of keys via keyword arguments in standard elements. A script
+ has been added to automatically convert old usages where possible.
+
+
+v1.0.0-a3
+---------
+:octicon:`milestone` *released on 2023-02-02*
+
+**Fixed**
+
+- :pull:`908` - minor type hint issue with ``VdomDictConstructor``
+
+**Removed**
+
+- :pull:`907` - accidental import of reactpy.testing
+
+
+v1.0.0-a2
+---------
+:octicon:`milestone` *released on 2023-01-31*
+
+**Reverted**
+
+- :pull:`901` - reverts :pull:`886` due to :issue:`896`
+
+**Fixed**
+
+- :issue:`896` - Stale event handlers after disconnect/reconnect cycle
+- :issue:`898` - Fixed CLI not registered as entry point
+
+
+v1.0.0-a1
+---------
+:octicon:`milestone` *released on 2023-01-28*
+
+**Changed**
+
+- :pull:`841` - Revamped element constructor interface. Now instead of passing a
+ dictionary of attributes to element constructors, attributes are declared using
+ keyword arguments. For example, instead of writing:
+
+ .. code-block::
+
+ html.div({"className": "some-class"}, "some", "text")
+
+ You now should write:
+
+ .. code-block::
+
+ html.div("some", "text", class_name="some-class")
+
+ .. note::
+
+ All attributes are written using ``snake_case``.
+
+ In conjunction, with these changes, ReactPy now supplies a command line utility that
+ makes a "best effort" attempt to automatically convert code to the new API. Usage of
+ this utility is as follows:
+
+ .. code-block:: bash
+
+ reactpy update-html-usages [PATHS]
+
+ Where ``[PATHS]`` is any number of directories or files that should be rewritten.
+
+ .. warning::
+
+ After running this utility, code comments and formatting may have been altered. It's
+ recommended that you run a code formatting tool like `Black
+ `__ and manually review and replace any comments that
+ may have been moved.
+
+**Fixed**
+
+- :issue:`755` - unification of component and VDOM constructor interfaces. See above.
+
+
+v0.44.0
+-------
+:octicon:`milestone` *released on 2023-01-27*
+
+**Deprecated**
+
+- :pull:`876` - ``reactpy.widgets.hotswap``. The function has no clear uses outside of some
+ internal applications. For this reason it has been deprecated.
+
+**Removed**
+
+- :pull:`886` - Ability to access element value from events via `event['value']` key.
+ Instead element value should be accessed via `event['target']['value']`. Originally
+ deprecated in :ref:`v0.34.0`.
+- :pull:`886` - old misspelled option ``reactpy.config.REACTPY_WED_MODULES_DIR``. Originally
+ deprecated in :ref:`v0.36.1`.
+
+
+v0.43.0
+-------
+:octicon:`milestone` *released on 2023-01-09*
+
+**Deprecated**
+
+- :pull:`870` - ``ComponentType.should_render()``. This method was implemented based on
+ reading the React/Preact source code. As it turns out though it seems like it's mostly
+ a vestige from the fact that both these libraries still support class-based
+ components. The ability for components to not render also caused several bugs.
+
+**Fixed**
+
+- :issue:`846` - Nested context does no update value if outer context should not render.
+- :issue:`847` - Detached model state on render of context consumer if unmounted and
+ context value does not change.
+
+
+v0.42.0
+-------
+:octicon:`milestone` *released on 2022-12-02*
+
+**Added**
+
+- :pull:`835` - Ability to customize the ```` element of ReactPy's built-in client.
+- :pull:`835` - ``vdom_to_html`` utility function.
+- :pull:`843` - Ability to subscribe to changes that are made to mutable options.
+- :pull:`832` - ``del_html_head_body_transform`` to remove ````, ````, and ```` while preserving children.
+- :pull:`699` - Support for form element serialization
+
+**Fixed**
+
+- :issue:`582` - ``REACTPY_DEBUG_MODE`` is now mutable and can be changed at runtime
+- :pull:`832` - Fix ``html_to_vdom`` improperly removing ````, ````, and ```` nodes.
+
+**Removed**
+
+- :pull:`832` - Removed ``reactpy.html.body`` as it is currently unusable due to technological limitations, and thus not needed.
+- :pull:`840` - remove ``REACTPY_FEATURE_INDEX_AS_DEFAULT_KEY`` option
+- :pull:`835` - ``serve_static_files`` option from backend configuration
+
+**Deprecated**
+
+- :commit:`8f3785b` - Deprecated ``module_from_template``
+
+v0.41.0
+-------
+:octicon:`milestone` *released on 2022-11-01*
+
+**Changed**
+
+- :pull:`823` - The hooks ``use_location`` and ``use_scope`` are no longer
+ implementation specific and are now available as top-level imports. Instead of each
+ backend defining these hooks, backends establish a ``ConnectionContext`` with this
+ information.
+- :pull:`824` - ReactPy's built-in backend server now expose the following routes:
+
+ - ``/_reactpy/assets/``
+ - ``/_reactpy/stream/``
+ - ``/_reactpy/modules/``
+ - ``//``
+
+ This should allow the browser to cache static resources. Even if your ``url_prefix``
+ is ``/_reactpy``, your app should still work as expected. Though if you're using
+ ``reactpy-router``, ReactPy's server routes will always take priority.
+- :pull:`824` - Backend implementations now strip any URL prefix in the pathname for
+ ``use_location``.
+- :pull:`827` - ``use_state`` now returns a named tuple with ``value`` and ``set_value``
+ fields. This is convenient for adding type annotations if the initial state value is
+ not the same as the values you might pass to the state setter. Where previously you
+ might have to do something like:
+
+ .. code-block::
+
+ value: int | None = None
+ value, set_value = use_state(value)
+
+ Now you can annotate your state using the ``State`` class:
+
+ .. code-block::
+
+ state: State[int | None] = use_state(None)
+
+ # access value and setter
+ state.value
+ state.set_value
+
+ # can still destructure if you need to
+ value, set_value = state
+
+**Added**
+
+- :pull:`823` - There is a new ``use_connection`` hook which returns a ``Connection``
+ object. This ``Connection`` object contains a ``location`` and ``scope``, along with
+ a ``carrier`` which is unique to each backend implementation.
+
+
+v0.40.2
+-------
+:octicon:`milestone` *released on 2022-09-13*
+
+**Changed**
+
+- :pull:`809` - Avoid the use of JSON patch for diffing models.
+
+
+v0.40.1
+-------
+:octicon:`milestone` *released on 2022-09-11*
+
+**Fixed**
+
+- :issue:`806` - Child models after a component fail to render
+
+
+v0.40.0 (yanked)
+----------------
+:octicon:`milestone` *released on 2022-08-13*
+
+**Fixed**
+
+- :issue:`777` - Fix edge cases where ``html_to_vdom`` can fail to convert HTML
+- :issue:`789` - Conditionally rendered components cannot use contexts
+- :issue:`773` - Use strict equality check for text, numeric, and binary types in hooks
+- :issue:`801` - Accidental mutation of old model causes invalid JSON Patch
+
+**Changed**
+
+- :pull:`123` - set default timeout on playwright page for testing
+- :pull:`787` - Track contexts in hooks as state
+- :pull:`787` - remove non-standard ``name`` argument from ``create_context``
+
+**Added**
+
+- :pull:`123` - ``asgiref`` as a dependency
+- :pull:`795` - ``lxml`` as a dependency
+
+
+v0.39.0
+-------
+:octicon:`milestone` *released on 2022-06-20*
+
+**Fixed**
+
+- :pull:`763` - ``No module named 'reactpy.server'`` from ``reactpy.run``
+- :pull:`749` - Setting appropriate MIME type for web modules in `sanic` server implementation
+
+**Changed**
+
+- :pull:`763` - renamed various:
+
+ - ``reactpy.testing.server -> reactpy.testing.backend``
+ - ``ServerFixture -> BackendFixture``
+ - ``DisplayFixture.server -> DisplayFixture.backend``
+
+- :pull:`765` - ``exports_default`` parameter is removed from ``module_from_template``.
+
+**Added**
+
+- :pull:`765` - ability to specify versions with module templates (e.g.
+ ``module_from_template("react@^17.0.0", ...)``).
+
+
+v0.38.1
+-------
+:octicon:`milestone` *released on 2022-04-15*
+
+**Fixed**
+
+- `reactive-python/reactpy-jupyter#22 `__ -
+ a missing file extension was causing a problem with WebPack.
+
+
+v0.38.0
+-------
+:octicon:`milestone` *released on 2022-04-15*
+
+No changes.
+
+
+v0.38.0-a4
+----------
+:octicon:`milestone` *released on 2022-04-15*
+
+**Added**
+
+- :pull:`733` - ``use_debug_value`` hook
+
+**Changed**
+
+- :pull:`733` - renamed ``assert_reactpy_logged`` testing util to ``assert_reactpy_did_log``
+
+
+v0.38.0-a3
+----------
+:octicon:`milestone` *released on 2022-04-15*
+
+**Changed**
+
+- :pull:`730` - Layout context management is not async
+
+
+v0.38.0-a2
+----------
+:octicon:`milestone` *released on 2022-04-14*
+
+**Added**
+
+- :pull:`721` - Implement ``use_location()`` hook. Navigating to any route below the
+ root of the application will be reflected in the ``location.pathname``. This operates
+ in concert with how ReactPy's configured routes have changed. This will ultimately work
+ towards resolving :issue:`569`.
+
+**Changed**
+
+- :pull:`721` - The routes ReactPy configures on apps have changed
+
+ .. code-block:: text
+
+ prefix/_api/modules/* web modules
+ prefix/_api/stream websocket endpoint
+ prefix/* client react app
+
+ This means that ReactPy's client app is available at any route below the configured
+ ``url_prefix`` besides ``prefix/_api``. The ``_api`` route will likely remain a route
+ which is reserved by ReactPy. The route navigated to below the ``prefix`` will be shown
+ in ``use_location``.
+
+- :pull:`721` - ReactPy's client now uses Preact instead of React
+
+- :pull:`726` - Renamed ``reactpy.server`` to ``reactpy.backend``. Other references to "server
+ implementations" have been renamed to "backend implementations" throughout the
+ documentation and code.
+
+**Removed**
+
+- :pull:`721` - ``redirect_root`` server option
+
+
+v0.38.0-a1
+----------
+:octicon:`milestone` *released on 2022-03-27*
+
+**Changed**
+
+- :pull:`703` - How ReactPy integrates with servers. ``reactpy.run`` no longer accepts an app
+ instance to discourage use outside of testing. ReactPy's server implementations now
+ provide ``configure()`` functions instead. ``reactpy.testing`` has been completely
+ reworked in order to support async web drivers
+- :pull:`703` - ``PerClientStateServer`` has been functionally replaced by ``configure``
+
+**Added**
+
+- :issue:`669` - Access to underlying server requests via contexts
+
+**Removed**
+
+- :issue:`669` - Removed ``reactpy.widgets.multiview`` since basic routing view ``use_scope`` is
+ now possible as well as all ``SharedClientStateServer`` implementations.
+
+**Fixed**
+
+- :issue:`591` - ReactPy's test suite no longer uses sync web drivers
+- :issue:`678` - Updated Sanic requirement to ``>=21``
+- :issue:`657` - How we advertise ``reactpy.run``
+
+
+v0.37.2
+-------
+:octicon:`milestone` *released on 2022-03-27*
+
+**Changed**
+
+- :pull:`701` - The name of ``proto`` modules to ``types`` and added a top level
+ ``reactpy.types`` module
+
+**Fixed**
+
+- :pull:`716` - A typo caused ReactPy to use the insecure ``ws`` web-socket protocol on
+ pages loaded with ``https`` instead of the secure ``wss`` protocol
+
+
+v0.37.1
+-------
+:octicon:`milestone` *released on 2022-03-05*
+
+No changes.
+
+
+v0.37.1-a2
+----------
+:octicon:`milestone` *released on 2022-03-02*
+
+**Fixed:**
+
+- :issue:`684` - Revert :pull:`694` and by making ``value`` uncontrolled client-side
+
+
+v0.37.1-a1
+----------
+:octicon:`milestone` *released on 2022-02-28*
+
+**Fixed:**
+
+- :issue:`684` - ``onChange`` event for inputs missing key strokes
+
+
+v0.37.0
+-------
+:octicon:`milestone` *released on 2022-02-27*
+
+**Added:**
+
+- :issue:`682` - Support for keys in HTML fragments
+- :pull:`585` - Use Context Hook
+
+**Fixed:**
+
+- :issue:`690` - React warning about set state in unmounted component
+- :pull:`688` - Missing reset of schedule_render_later flag
+
+----
+
+Releases below do not use the "Keep a Changelog" style guidelines.
+
+----
+
+v0.36.3
+-------
+:octicon:`milestone` *released on 2022-02-18*
+
+Misc bug fixes along with a minor improvement that allows components to return ``None``
+to render nothing.
+
+**Closed Issues**
+
+- All child states wiped upon any child key change - :issue:`652`
+- Allow NoneType returns within components - :issue:`538`
+
+**Merged Pull Requests**
+
+- fix #652 - :pull:`672`
+- Fix 663 - :pull:`667`
+
+
+v0.36.2
+-------
+:octicon:`milestone` *released on 2022-02-02*
+
+Hot fix for newly introduced ``DeprecatedOption``:
+
+- :commit:`c146dfb264cbc3d2256a62efdfe9ccf62c795b01`
+
+
+v0.36.1
+-------
+:octicon:`milestone` *released on 2022-02-02*
+
+Includes bug fixes and renames the configuration option ``REACTPY_WED_MODULES_DIR`` to
+``REACTPY_WEB_MODULES_DIR`` with a corresponding deprecation warning.
+
+**Closed Issues**
+
+- Fix Key Error When Cleaning Up Event Handlers - :issue:`640`
+- Update Script Tag Behavior - :issue:`628`
+
+**Merged Pull Requests**
+
+- mark old state as None if unmounting - :pull:`641`
+- rename REACTPY_WED_MODULES_DIR to REACTPY_WEB_MODULES_DIR - :pull:`638`
+
+
+v0.36.0
+-------
+:octicon:`milestone` *released on 2022-01-30*
+
+This release includes an important fix for errors produced after :pull:`623` was merged.
+In addition there is not a new ``http.script`` element which can behave similarly to a
+standard HTML ``
diff --git a/docs/source/getting-started/_static/embed-idom-view/index.html b/docs/source/getting-started/_static/embed-idom-view/index.html
deleted file mode 100644
index 3080e1d5d..000000000
--- a/docs/source/getting-started/_static/embed-idom-view/index.html
+++ /dev/null
@@ -1,39 +0,0 @@
-
-
-
-
- Example App
-
-
-
This is an Example App
-
Just below is an embedded IDOM view...
-
-
-
-
diff --git a/docs/source/getting-started/_static/embed-idom-view/main.py b/docs/source/getting-started/_static/embed-idom-view/main.py
deleted file mode 100644
index 0c0cb5ac0..000000000
--- a/docs/source/getting-started/_static/embed-idom-view/main.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from sanic import Sanic
-from sanic.response import file
-
-from idom import component, html
-from idom.server.sanic import Config, PerClientStateServer
-
-
-app = Sanic(__name__)
-
-
-@app.route("/")
-async def index(request):
- return await file("index.html")
-
-
-@component
-def IdomView():
- return html.code("This text came from an IDOM App")
-
-
-PerClientStateServer(IdomView, app=app, config=Config(url_prefix="/_idom"))
-
-app.run(host="127.0.0.1", port=5000)
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
deleted file mode 100644
index 0a5ed4daf..000000000
--- a/docs/source/getting-started/index.rst
+++ /dev/null
@@ -1,108 +0,0 @@
-Getting Started
-===============
-
-.. toctree::
- :hidden:
-
- installing-idom
- running-idom
-
-.. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
- :color: info
- :animate: fade-in
- :open:
-
- .. grid:: 1 2 2 2
-
- .. grid-item-card:: :octicon:`tools` Installing IDOM
- :link: installing-idom
- :link-type: doc
-
- Learn how IDOM can be installed in a variety of different ways - with different web
- servers and even in different frameworks.
-
- .. grid-item-card:: :octicon:`play` Running IDOM
- :link: running-idom
- :link-type: doc
-
- See the ways that IDOM can be run with servers or be embedded in existing
- applications.
-
-The fastest way to get started with IDOM is to try it out in a `Juptyer Notebook
-`__.
-If you want to use a Notebook to work through the examples shown in this documentation,
-you'll need to replace calls to ``idom.run(App)`` with a line at the end of each cell
-that constructs the ``App()`` in question. If that doesn't make sense, the introductory
-notebook linked below will demonstrate how to do this:
-
-.. card::
- :link: https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb
-
- .. image:: _static/idom-in-jupyterlab.gif
- :scale: 72%
- :align: center
-
-
-Section 1: Installing IDOM
---------------------------
-
-The next fastest option is to install IDOM with ``pip``:
-
-.. code-block:: bash
-
- pip install "idom[stable]"
-
-To check that everything is working you can run the sample application:
-
-.. code-block:: bash
-
- python -c "import idom; idom.run_sample_app(open_browser=True)"
-
-This should automatically open up a browser window to a page that looks like this:
-
-.. card::
-
- .. idom-view:: _examples/sample_app
-
-If you get a ``RuntimeError`` similar to the following:
-
-.. code-block:: text
-
- Found none of the following builtin server implementations...
-
-Then be sure you installed ``"idom[stable]"`` and not just ``idom``.
-
-For anything else, report your issue in IDOM's :discussion-type:`discussion forum
-`.
-
-.. card::
- :link: installing-idom
- :link-type: doc
-
- :octicon:`book` Read More
- ^^^^^^^^^^^^^^^^^^^^^^^^^
-
- Learn how IDOM can be installed in a variety of different ways - with different web
- servers and even in different frameworks.
-
-
-Section 2: Running IDOM
------------------------
-
-Once you've :ref:`installed IDOM `. The simplest way to run IDOM is
-with the :func:`~idom.server.prefab.run` function. By default this will execute your
-application using one of the builtin server implementations whose dependencies have all
-been installed. Running a tiny "hello world" application just requires the following
-code:
-
-.. idom:: _examples/hello_world
-
-.. card::
- :link: running-idom
- :link-type: doc
-
- :octicon:`book` Read More
- ^^^^^^^^^^^^^^^^^^^^^^^^^
-
- See the ways that IDOM can be run with servers or be embedded in existing
- applications.
diff --git a/docs/source/getting-started/installing-idom.rst b/docs/source/getting-started/installing-idom.rst
deleted file mode 100644
index a9082972d..000000000
--- a/docs/source/getting-started/installing-idom.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-Installing IDOM
-===============
-
-The easiest way to ``pip`` install idom is to do so using the ``stable`` option:
-
-.. code-block:: bash
-
- pip install "idom[stable]"
-
-This includes a set of default dependencies for one of the builtin web server
-implementation. If you want to install IDOM without these dependencies you may simply
-``pip install idom``.
-
-
-Installing Other Servers
-------------------------
-
-IDOM includes built-in support for a variety web server implementations. To install the
-required dependencies for each you should substitute ``stable`` from the ``pip install``
-command above with one of the options below:
-
-- ``fastapi`` - https://fastapi.tiangolo.com
-- ``flask`` - https://palletsprojects.com/p/flask/
-- ``sanic`` - https://sanicframework.org
-- ``tornado`` - https://www.tornadoweb.org/en/stable/
-
-If you need to, you can install more than one option by separating them with commas:
-
-.. code-block:: bash
-
- pip install idom[fastapi,flask,sanic,tornado]
-
-Once this is complete you should be able to :ref:`run IDOM ` with your
-:ref:`chosen server implementation `.
-
-
-Installing In Other Frameworks
-------------------------------
-
-While IDOM can run in a variety of contexts, sometimes web frameworks require extra work
-in order to integrate with them. In these cases, the IDOM team distributes bindings for
-various frameworks as separate Python packages. For documentation on how to install and
-run IDOM in the supported frameworks, follow the links below:
-
-.. raw:: html
-
-
-
-.. role:: transparent-text-color
-
-.. We add transparent-text-color to the text so it's not visible, but it's still
-.. searchable.
-
-.. grid:: 3
-
- .. grid-item-card::
- :link: https://github.com/idom-team/django-idom
- :img-background: _static/logo-django.svg
- :class-card: card-logo-image
-
- :transparent-text-color:`Django`
-
- .. grid-item-card::
- :link: https://github.com/idom-team/idom-jupyter
- :img-background: _static/logo-jupyter.svg
- :class-card: card-logo-image
-
- :transparent-text-color:`Jupyter`
-
- .. grid-item-card::
- :link: https://github.com/idom-team/idom-dash
- :img-background: _static/logo-plotly.svg
- :class-card: card-logo-image
-
- :transparent-text-color:`Plotly Dash`
-
-
-Installing for Development
---------------------------
-
-If you want to contribute to the development of IDOM or modify it, you'll want to
-install a development version of IDOM. This involves cloning the repository where IDOM's
-source is maintained, and setting up a :ref:`development environment`. From there you'll
-be able to modifying IDOM's source code and :ref:`run its tests ` to
-ensure the modifications you've made are backwards compatible. If you want to add a new
-feature to IDOM you should write your own test that validates its behavior.
-
-If you have questions about how to modify IDOM or help with its development, be sure to
-`start a discussion
-`__. The IDOM team
-are always excited to :ref:`welcome ` new contributions and
-contributors of all kinds
-
-.. card::
- :link: /developing-idom/index
- :link-type: doc
-
- :octicon:`book` Read More
- ^^^^^^^^^^^^^^^^^^^^^^^^^
-
- Learn more about how to contribute to the development of IDOM.
diff --git a/docs/source/getting-started/running-idom.rst b/docs/source/getting-started/running-idom.rst
deleted file mode 100644
index 3b180f6e5..000000000
--- a/docs/source/getting-started/running-idom.rst
+++ /dev/null
@@ -1,290 +0,0 @@
-Running IDOM
-============
-
-The simplest way to run IDOM is with the :func:`~idom.server.prefab.run` function. By
-default this will execute your application using one of the builtin server
-implementations whose dependencies have all been installed. Running a tiny "hello world"
-application just requires the following code:
-
-.. idom:: _examples/hello_world
-
-.. note::
-
- Try clicking the **âļī¸ Result** tab to see what this displays!
-
-
-Running IDOM in Debug Mode
---------------------------
-
-IDOM provides a debug mode that is turned off by default. This can be enabled when you
-run your application by setting the ``IDOM_DEBUG_MODE`` environment variable.
-
-.. tab-set::
-
- .. tab-item:: Unix Shell
-
- .. code-block::
-
- export IDOM_DEBUG_MODE=1
- python my_idom_app.py
-
- .. tab-item:: Command Prompt
-
- .. code-block:: text
-
- set IDOM_DEBUG_MODE=1
- python my_idom_app.py
-
- .. tab-item:: PowerShell
-
- .. code-block:: powershell
-
- $env:IDOM_DEBUG_MODE = "1"
- python my_idom_app.py
-
-.. danger::
-
- Leave debug mode off in production!
-
-Among other things, running in this mode:
-
-- Turns on debug log messages
-- Adds checks to ensure the :ref:`VDOM` spec is adhered to
-- Displays error messages that occur within your app
-
-Errors will be displayed where the uppermost component is located in the view:
-
-.. idom:: _examples/debug_error_example
-
-
-Choosing a Server Implementation
---------------------------------
-
-Without extra care, running an IDOM app with the ``run()`` function can be somewhat
-inpredictable since the kind of server being used by default depends on what gets
-discovered first. To be more explicit about which server implementation you want to run
-with you can import your chosen server class and pass it to the ``server_type``
-parameter of ``run()``:
-
-.. code-block::
-
- from idom import component, html, run
- from idom.server.sanic import PerClientStateServer
-
-
- @component
- def App():
- return html.h1(f"Hello, World!")
-
-
- run(App, server_type=PerClientStateServer)
-
-Presently IDOM's core library supports the following server implementations:
-
-- :mod:`idom.server.fastapi`
-- :mod:`idom.server.sanic`
-- :mod:`idom.server.flask`
-- :mod:`idom.server.tornado`
-
-.. hint::
-
- To install them, see the :ref:`Installing Other Servers` section.
-
-
-Available Server Types
-----------------------
-
-Some of server implementations have more than one server type available. The server type
-which exists for all implementations is the ``PerClientStateServer``. This server type
-displays a unique view to each user who visits the site. For those that support it,
-there may also be a ``SharedClientStateServer`` available. This server type presents the
-same view to all users who visit the site. For example, if you were to run the following
-code:
-
-.. code-block::
-
- from idom import component, hooks, html, run
- from idom.server.sanic import SharedClientStateServer
-
-
- @component
- def Slider():
- value, set_value = hooks.use_state(50)
- return html.input({"type": "range", "min": 1, "max": 100, "value": value})
-
-
- run(Slider, server_type=SharedClientStateServer)
-
-Two clients could see the slider and see a synchronized view of it. That is, when one
-client moved the slider, the other would see the slider update without their action.
-This might look similar to the video below:
-
-.. image:: _static/shared-client-state-server-slider.gif
-
-Presently the following server implementations support the ``SharedClientStateServer``:
-
-- :func:`idom.server.fastapi.SharedClientStateServer`
-- :func:`idom.server.sanic.SharedClientStateServer`
-
-.. note::
-
- If you need to, your can :ref:`write your own server implementation `.
-
-Common Server Settings
-----------------------
-
-Each server implementation has its own high-level settings that are defined by its
-respective ``Config`` (a typed dictionary). As a general rule, these ``Config`` types
-expose the same options across implementations. These configuration dictionaries can
-then be passed to the ``run()`` function via the ``config`` parameter:
-
-.. code-block::
-
- from idom import run, component, html
- from idom.server.sanic import PerClientStateServer, Config
-
-
- @component
- def App():
- return html.h1(f"Hello, World!")
-
-
- server_config = Config(
- cors=False,
- url_prefix="",
- serve_static_files=True,
- redirect_root_to_index=True,
- )
-
- run(App, server_type=PerClientStateServer, config=server_config)
-
-Here's the list of available configuration types:
-
-- :class:`idom.server.fastapi.Config`
-- :class:`idom.server.sanic.Config`
-- :class:`idom.server.flask.Config`
-- :class:`idom.server.tornado.Config`
-
-
-Specific Server Settings
-------------------------
-
-The ``Config`` :ref:`described above ` is meant to be an
-implementation agnostic - all ``Config`` objects support a similar set of options.
-However, there are inevitably cases where you need to set up your chosen server using
-implementation specific details. For instance, you might want to add an extra route to
-the server your using in order to provide extra resources to your application.
-
-Doing this kind of set up can be achieved by passing in an instance of your chosen
-server implementation into the ``app`` parameter of the ``run()`` function. To
-illustrate, if I'm making my application with ``sanic`` and I want to add an extra route
-I would do the following:
-
-.. code-block::
-
- from sanic import Sanic
- from idom import component, html, run
- from idom.server.sanic import PerClientStateServer
-
- app = Sanic(__name__)
-
- # these are implementation specific settings only known to `sanic` servers
- app.config.REQUEST_TIMEOUT = 60
- app.config.RESPONSE_TIMEOUT = 60
-
-
- @component
- def SomeView():
- return html.form({"action": })
-
-
- run(SomeView, server_type=PerClientStateServer, app=app)
-
-
-Add to an Existing Web Server
------------------------------
-
-If you're already serving an application with one of the supported web servers listed
-above, you can add an IDOM to them as a server extension. Instead of using the ``run()``
-function, you'll instantiate one of IDOM's server implementations by passing it an
-instance of your existing application:
-
-.. code-block::
-
- from sanic import Sanic
-
- from idom import component, html
- from idom.server.sanic import PerClientStateServer, Config
-
- existing_app = Sanic(__name__)
-
-
- @component
- def IdomView():
- return html.h1("This is an IDOM App")
-
-
- PerClientStateServer(IdomView, app=existing_app, config=Config(url_prefix="app"))
-
- existing_app.run(host="127.0.0.1", port=8000)
-
-To test that everything is working, you should be able to navigate to
-``https://127.0.0.1:8000/app`` where you should see the results from ``IdomView``.
-
-
-Embed in an Existing Webpage
-----------------------------
-
-IDOM provides a Javascript client called ``idom-client-react`` that can be used to embed
-IDOM views within an existing applications. This is actually how the interactive
-examples throughout this documentation have been created. You can try this out by
-embedding one the examples from this documentation into your own webpage:
-
-.. tab-set::
-
- .. tab-item:: HTML
-
- .. literalinclude:: _static/embed-doc-ex.html
- :language: html
-
- .. tab-item:: âļī¸ Result
-
- .. raw:: html
- :file: _static/embed-doc-ex.html
-
-.. note::
-
- For more information on how to use the client see the :ref:`Javascript API`
- reference. Or if you need to, your can :ref:`write your own server implementation
- `.
-
-As mentioned though, this is connecting to the server that is hosting this
-documentation. If you want to connect to a view from your own server, you'll need to
-change the URL above to one you provide. One way to do this might be to :ref:`add to an
-existing web server`. Another would be to run IDOM in an adjacent web server instance
-that you coordinate with something like `NGINX `__. For the sake
-of simplicity, we'll assume you do something similar to the following in an existing
-Python app:
-
-.. tab-set::
-
- .. tab-item:: main.py
-
- .. literalinclude:: _static/embed-idom-view/main.py
- :language: python
-
- .. tab-item:: index.html
-
- .. literalinclude:: _static/embed-idom-view/index.html
- :language: html
-
-After running ``python main.py``, you should be able to navigate to
-``http://127.0.0.1:8000/index.html`` and see:
-
-.. card::
- :text-align: center
-
- .. image:: _static/embed-idom-view/screenshot.png
- :width: 500px
-
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json
similarity index 97%
rename from docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json
index b2a2ba966..b1315912d 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/data.json
@@ -44,7 +44,7 @@
{
"name": "Terracotta Army",
"artist": "Unknown Artist",
- "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consited of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
+ "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consisted of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg/1920px-2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg",
"alt": "12 terracotta sculptures of solemn warriors, each with a unique facial expression and armor."
},
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/main.py
similarity index 81%
rename from docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/main.py
index 5a96d2f03..a919a2354 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/main.py
@@ -1,8 +1,7 @@
import json
from pathlib import Path
-from idom import component, hooks, html, run
-
+from reactpy import component, hooks, html, run
HERE = Path(__file__)
DATA_PATH = HERE.parent / "data.json"
@@ -25,9 +24,9 @@ def handle_click(event):
url = sculpture["url"]
return html.div(
- html.button({"onClick": handle_click}, "Next"),
+ html.button({"on_click": handle_click}, "Next"),
html.h2(name, " by ", artist),
- html.p(f"({bounded_index + 1} or {len(sculpture_data)})"),
+ html.p(f"({bounded_index + 1} of {len(sculpture_data)})"),
html.img({"src": url, "alt": alt, "style": {"height": "200px"}}),
html.p(description),
)
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/data.json
similarity index 97%
rename from docs/source/adding-interactivity/components-with-state/_examples/isolated_state/data.json
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/data.json
index b2a2ba966..b1315912d 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/data.json
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/data.json
@@ -44,7 +44,7 @@
{
"name": "Terracotta Army",
"artist": "Unknown Artist",
- "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consited of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
+ "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consisted of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg/1920px-2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg",
"alt": "12 terracotta sculptures of solemn warriors, each with a unique facial expression and armor."
},
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/main.py
similarity index 84%
rename from docs/source/adding-interactivity/components-with-state/_examples/isolated_state/app.py
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/main.py
index 08a53d1c6..d07b87140 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/isolated_state/app.py
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/main.py
@@ -1,8 +1,7 @@
import json
from pathlib import Path
-from idom import component, hooks, html, run
-
+from reactpy import component, hooks, html, run
HERE = Path(__file__)
DATA_PATH = HERE.parent / "data.json"
@@ -29,14 +28,14 @@ def handle_more_click(event):
url = sculpture["url"]
return html.div(
- html.button({"onClick": handle_next_click}, "Next"),
+ html.button({"on_click": handle_next_click}, "Next"),
html.h2(name, " by ", artist),
html.p(f"({bounded_index + 1} or {len(sculpture_data)})"),
html.img({"src": url, "alt": alt, "style": {"height": "200px"}}),
html.div(
html.button(
- {"onClick": handle_more_click},
- f"{'Show' if show_more else 'Hide'} details",
+ {"on_click": handle_more_click},
+ f"{('Show' if show_more else 'Hide')} details",
),
(html.p(description) if show_more else ""),
),
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json
similarity index 97%
rename from docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json
index b2a2ba966..b1315912d 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/data.json
@@ -44,7 +44,7 @@
{
"name": "Terracotta Army",
"artist": "Unknown Artist",
- "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consited of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
+ "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consisted of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg/1920px-2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg",
"alt": "12 terracotta sculptures of solemn warriors, each with a unique facial expression and armor."
},
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/main.py
similarity index 81%
rename from docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/main.py
index 3e7f7bde4..87f9651be 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/main.py
@@ -1,8 +1,7 @@
import json
from pathlib import Path
-from idom import component, hooks, html, run
-
+from reactpy import component, hooks, html, run
HERE = Path(__file__)
DATA_PATH = HERE.parent / "data.json"
@@ -29,14 +28,14 @@ def handle_more_click(event):
url = sculpture["url"]
return html.div(
- html.button({"onClick": handle_next_click}, "Next"),
+ html.button({"on_click": handle_next_click}, "Next"),
html.h2(name, " by ", artist),
html.p(f"({bounded_index + 1} or {len(sculpture_data)})"),
html.img({"src": url, "alt": alt, "style": {"height": "200px"}}),
html.div(
html.button(
- {"onClick": handle_more_click},
- f"{'Show' if show_more else 'Hide'} details",
+ {"on_click": handle_more_click},
+ f"{('Show' if show_more else 'Hide')} details",
),
(html.p(description) if show_more else ""),
),
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/data.json b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/data.json
similarity index 97%
rename from docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/data.json
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/data.json
index b2a2ba966..b1315912d 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/data.json
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/data.json
@@ -44,7 +44,7 @@
{
"name": "Terracotta Army",
"artist": "Unknown Artist",
- "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consited of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
+ "description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consisted of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg/1920px-2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg",
"alt": "12 terracotta sculptures of solemn warriors, each with a unique facial expression and armor."
},
diff --git a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/app.py b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/main.py
similarity index 89%
rename from docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/app.py
rename to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/main.py
index f8679cbfc..c617586de 100644
--- a/docs/source/adding-interactivity/components-with-state/_examples/when_variables_arent_enough/app.py
+++ b/docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/main.py
@@ -7,7 +7,7 @@
import json
from pathlib import Path
-from idom import component, html, run
+from reactpy import component, html, run
HERE = Path(__file__)
@@ -31,7 +31,7 @@ def handle_click(event):
url = sculpture["url"]
return html.div(
- html.button({"onClick": handle_click}, "Next"),
+ html.button({"on_click": handle_click}, "Next"),
html.h2(name, " by ", artist),
html.p(f"({bounded_index + 1} or {len(sculpture_data)})"),
html.img({"src": url, "alt": alt, "style": {"height": "200px"}}),
diff --git a/docs/source/adding-interactivity/components-with-state/index.rst b/docs/source/guides/adding-interactivity/components-with-state/index.rst
similarity index 81%
rename from docs/source/adding-interactivity/components-with-state/index.rst
rename to docs/source/guides/adding-interactivity/components-with-state/index.rst
index 2542d97bb..f8235ac0d 100644
--- a/docs/source/adding-interactivity/components-with-state/index.rst
+++ b/docs/source/guides/adding-interactivity/components-with-state/index.rst
@@ -5,7 +5,7 @@ Components often need to change whatâs on the screen as a result of an interac
example, typing into the form should update the input field, clicking ânextâ on an image
carousel should change which image is displayed, clicking âbuyâ should put a product in
the shopping cart. Components need to ârememberâ things like the current input value,
-the current image, the shopping cart. In IDOM, this kind of component-specific memory is
+the current image, the shopping cart. In ReactPy, this kind of component-specific memory is
called state.
@@ -16,13 +16,13 @@ Below is a gallery of images about sculpture. Clicking the "Next" button should
increment the ``index`` and, as a result, change what image is displayed. However, this
does not work:
-.. idom:: _examples/when_variables_arent_enough
+.. reactpy:: _examples/when_variables_are_not_enough
.. note::
Try clicking the button to see that it does not cause a change.
-After clicking "Next", if you check the server logs, you'll discover an
+After clicking "Next", if you check your web server's logs, you'll discover an
``UnboundLocalError`` error. It turns out that in this case, the ``index = index + 1``
statement is similar to `trying to set global variables
`__.
@@ -36,13 +36,13 @@ that still wouldn't fix the underlying problems:
destroyed when it updates.
2. **Changes to local variables do not cause components to re-render** - there's no way
- for IDOM to observe when these variables change. Thus IDOM is not aware that
+ for ReactPy to observe when these variables change. Thus ReactPy is not aware that
something has changed and that a re-render should take place.
-To address these problems, IDOM provides the :func:`~idom.core.hooks.use_state` "hook"
+To address these problems, ReactPy provides the :func:`~reactpy.core.hooks.use_state` "hook"
which provides:
-1. A **state variable** whose data is retained aross renders.
+1. A **state variable** whose data is retained across renders.
2. A **state setter** function that can be used to update that variable and trigger a
render.
@@ -51,12 +51,12 @@ which provides:
Adding State to Components
--------------------------
-To create a state variable and state setter with :func:`~idom.core.hooks.use_state` hook
+To create a state variable and state setter with :func:`~reactpy.core.hooks.use_state` hook
as described above, we'll begin by importing it:
.. testcode::
- from idom import use_state
+ from reactpy import use_state
Then we'll make the following changes to our code :ref:`from before `:
@@ -84,16 +84,16 @@ After making those changes we should get:
We'll talk more about what this is doing :ref:`shortly `, but for
now let's just verify that this does in fact fix the problems from before:
-.. idom:: _examples/adding_state_variable
+.. reactpy:: _examples/adding_state_variable
Your First Hook
---------------
-In IDOM, ``use_state``, as well as any other function whose name starts with ``use``, is
-called a "hook". These are special functions that should only be called while IDOM is
+In ReactPy, ``use_state``, as well as any other function whose name starts with ``use``, is
+called a "hook". These are special functions that should only be called while ReactPy is
:ref:`rendering `. They let you "hook into" the different
-capabilities of IDOM's components of which ``use_state`` is just one (well get into the
+capabilities of ReactPy's components of which ``use_state`` is just one (well get into the
other :ref:`later `).
While hooks are just normal functions, but it's helpful to think of them as
@@ -107,7 +107,7 @@ words, you'll "use" hooks at the top of your component in the same way you might
Introduction to ``use_state``
-----------------------------
-When you call :func:`~idom.core.hooks.use_state` inside the body of a component's render
+When you call :func:`~reactpy.core.hooks.use_state` inside the body of a component's render
function, you're declaring that this component needs to remember something. That
"something" which needs to be remembered, is known as **state**. So when we look at an
assignment expression like the one below
@@ -130,7 +130,7 @@ Thus, in this example:
of the component.
The convention is that, if you name your state variable ``thing``, your state setter
-should be named ``set_thing``. While you could name them anything you want, adhereing to
+should be named ``set_thing``. While you could name them anything you want, adhering to
the convention makes things easier to understand across projects.
----
@@ -151,12 +151,12 @@ below highlights a line of code where something of interest occurs:
Initial render
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 2
At this point, we've just begun to render the ``Gallery`` component. As yet,
- IDOM is not aware that this component has any state or what view it will
+ ReactPy is not aware that this component has any state or what view it will
display. This will change in a moment though when we move to the next line...
.. tab-item:: 2
@@ -165,11 +165,11 @@ below highlights a line of code where something of interest occurs:
Initial state declaration
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 3
- The ``Gallery`` component has just declared some state. IDOM now knows that it
+ The ``Gallery`` component has just declared some state. ReactPy now knows that it
must remember the ``index`` and trigger an update of this component when
``set_index`` is called. Currently the value of ``index`` is ``0`` as per the
default value given to ``use_state``. Thus, the resulting view will display
@@ -181,7 +181,7 @@ below highlights a line of code where something of interest occurs:
Define event handler
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 5
@@ -196,7 +196,7 @@ below highlights a line of code where something of interest occurs:
Return the view
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 16
@@ -212,11 +212,11 @@ below highlights a line of code where something of interest occurs:
User interaction
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 5
- A user has just clicked the button đąī¸! IDOM has sent information about the event
+ A user has just clicked the button đąī¸! ReactPy has sent information about the event
to the ``handle_click`` function and it is about to execute. In a moment we will
update the state of this component and schedule a re-render.
@@ -226,11 +226,11 @@ below highlights a line of code where something of interest occurs:
New state is set
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 6
- We've just now told IDOM that we want to update the state of our ``Gallery`` and
+ We've just now told ReactPy that we want to update the state of our ``Gallery`` and
that it needs to be re-rendered. More specifically, we are incrementing its
``index``, and once ``Gallery`` re-renders the index *will* be ``1``.
Importantly, at this point, the value of ``index`` is still ``0``! This will
@@ -242,11 +242,11 @@ below highlights a line of code where something of interest occurs:
Next render begins
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 2
- The scheduled re-render of ``Gallery`` has just begun. IDOM has now updated its
+ The scheduled re-render of ``Gallery`` has just begun. ReactPy has now updated its
internal state store such that, the next time we call ``use_state`` we will get
back the updated value of ``index``.
@@ -256,12 +256,12 @@ below highlights a line of code where something of interest occurs:
Next state is acquired
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
:emphasize-lines: 3
- With IDOM's state store updated, as we call ``use_state``, instead of returning
- ``0`` for the value of ``index`` as it did before, IDOM now returns the value
+ With ReactPy's state store updated, as we call ``use_state``, instead of returning
+ ``0`` for the value of ``index`` as it did before, ReactPy now returns the value
``1``. With this change the view we display will be altered - instead of
displaying data for the first item in our ``sculpture_data`` list we will now
display information about the second.
@@ -272,7 +272,7 @@ below highlights a line of code where something of interest occurs:
Repeat...
- .. literalinclude:: _examples/adding_state_variable/app.py
+ .. literalinclude:: _examples/adding_state_variable/main.py
:lines: 12-33
From this point on, the steps remain the same. The only difference being the
@@ -293,14 +293,14 @@ below highlights a line of code where something of interest occurs:
Multiple State Declarations
---------------------------
-The powerful thing about hooks like :func:`~idom.core.hooks.use_state` is that you're
+The powerful thing about hooks like :func:`~reactpy.core.hooks.use_state` is that you're
not limited to just one state declaration. You can call ``use_state()`` as many times as
you need to in one component. For example, in the example below we've added a
``show_more`` state variable along with a few other modifications (e.g. renaming
``handle_click``) to make the description for each sculpture optionally displayed. Only
when the user clicks the "Show details" button is this description shown:
-.. idom:: _examples/multiple_state_variables
+.. reactpy:: _examples/multiple_state_variables
It's generally a good idea to define separate state variables if the data they represent
is unrelated. In this case, ``index`` corresponds to what sculpture information is being
@@ -308,7 +308,7 @@ displayed and ``show_more`` is solely concerned with whether the description for
sculpture is shown. Put other way ``index`` is concerned with *what* information is
displayed while ``show_more`` is concerned with *how* it is displayed. Conversely
though, if you have a form with many fields, it probably makes sense to have a single
-objec that holds the data for all the fields rather than an object per-field.
+object that holds the data for all the fields rather than an object per-field.
.. note::
@@ -326,7 +326,7 @@ In this example, the ``Gallery`` component from earlier is rendered twice with n
changes to its logic. Try clicking the buttons inside each of the galleries. Notice that
their state is independent:
-.. idom:: _examples/isolated_state
+.. reactpy:: _examples/isolated_state
:result-is-default-tab:
This is what makes state different from regular variables that you might declare at the
@@ -340,12 +340,12 @@ it. The parent component canât change it. This lets you add state to any compo
remove it without impacting the rest of the components.
.. card::
- :link: /managing-state/shared-component-state
+ :link: /guides/managing-state/sharing-component-state/index
:link-type: doc
:octicon:`book` Read More
^^^^^^^^^^^^^^^^^^^^^^^^^
What if you wanted both galleries to keep their states in sync? The right way to do
- it in IDOM is to remove state from child components and add it to their closest
+ it in ReactPy is to remove state from child components and add it to their closest
shared parent.
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py
similarity index 77%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py
index cf1955301..6c3c783da 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -26,29 +26,29 @@ def handle_click(event):
return handle_click
return html.div(
- html.button({"onClick": handle_add_click}, "add term"),
+ html.button({"on_click": handle_add_click}, "add term"),
html.label(
"Term: ",
- html.input({"value": term_to_add, "onChange": handle_term_to_add_change}),
+ html.input({"value": term_to_add, "on_change": handle_term_to_add_change}),
),
html.label(
"Definition: ",
html.input(
{
"value": definition_to_add,
- "onChange": handle_definition_to_add_change,
+ "on_change": handle_definition_to_add_change,
}
),
),
html.hr(),
[
html.div(
+ {"key": term},
html.button(
- {"onClick": make_delete_click_handler(term)}, "delete term"
+ {"on_click": make_delete_click_handler(term)}, "delete term"
),
html.dt(term),
html.dd(definition),
- key=term,
)
for term, definition in all_terms.items()
],
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
similarity index 68%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
index 9a2aad5e6..32dd4073a 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -24,20 +24,18 @@ def handle_email_change(event):
html.label(
"First name: ",
html.input(
- {"value": person["first_name"], "onChange": handle_first_name_change},
+ {"value": person["first_name"], "on_change": handle_first_name_change}
),
),
html.label(
- "First name: ",
+ "Last name: ",
html.input(
- {"value": person["last_name"], "onChange": handle_last_name_change},
+ {"value": person["last_name"], "on_change": handle_last_name_change}
),
),
html.label(
- "First name: ",
- html.input(
- {"value": person["email"], "onChange": handle_email_change},
- ),
+ "Email: ",
+ html.input({"value": person["email"], "on_change": handle_email_change}),
),
html.p(f"{person['first_name']} {person['last_name']} {person['email']}"),
)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_insert.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_insert.py
similarity index 65%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_insert.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_insert.py
index 374198f45..1f4072e0b 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_insert.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_insert.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -16,9 +16,9 @@ def handle_click(event):
return html.div(
html.h1("Inspiring sculptors:"),
- html.input({"value": artist_to_add, "onChange": handle_change}),
- html.button({"onClick": handle_click}, "add"),
- html.ul([html.li(name, key=name) for name in artists]),
+ html.input({"value": artist_to_add, "on_change": handle_change}),
+ html.button({"on_click": handle_click}, "add"),
+ html.ul([html.li({"key": name}, name) for name in artists]),
)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py
similarity index 55%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py
index 32a0e47c0..3bd2fd601 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_re_order.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -8,16 +8,16 @@ def ArtistList():
)
def handle_sort_click(event):
- set_artists(list(sorted(artists)))
+ set_artists(sorted(artists))
def handle_reverse_click(event):
set_artists(list(reversed(artists)))
return html.div(
html.h1("Inspiring sculptors:"),
- html.button({"onClick": handle_sort_click}, "sort"),
- html.button({"onClick": handle_reverse_click}, "reverse"),
- html.ul([html.li(name, key=name) for name in artists]),
+ html.button({"on_click": handle_sort_click}, "sort"),
+ html.button({"on_click": handle_reverse_click}, "reverse"),
+ html.ul([html.li({"key": name}, name) for name in artists]),
)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_remove.py
similarity index 71%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_remove.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_remove.py
index 170deb2f4..6223284f6 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_remove.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_remove.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -24,14 +24,16 @@ def handle_click(event):
return html.div(
html.h1("Inspiring sculptors:"),
- html.input({"value": artist_to_add, "onChange": handle_change}),
- html.button({"onClick": handle_add_click}, "add"),
+ html.input({"value": artist_to_add, "on_change": handle_change}),
+ html.button({"on_click": handle_add_click}, "add"),
html.ul(
[
html.li(
+ {"key": name},
name,
- html.button({"onClick": make_handle_delete_click(index)}, "delete"),
- key=name,
+ html.button(
+ {"on_click": make_handle_delete_click(index)}, "delete"
+ ),
)
for index, name in enumerate(artists)
]
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_replace.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_replace.py
similarity index 74%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/list_replace.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_replace.py
index 2fafcfde8..4952b9597 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/list_replace.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/list_replace.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -15,9 +15,9 @@ def handle_click(event):
return html.ul(
[
html.li(
+ {"key": index},
count,
- html.button({"onClick": make_increment_click_handler(index)}, "+1"),
- key=index,
+ html.button({"on_click": make_increment_click_handler(index)}, "+1"),
)
for index, count in enumerate(counters)
]
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py
similarity index 79%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py
index d3edb8590..e5ab54dca 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -17,26 +17,26 @@ async def handle_pointer_move(event):
return html.div(
{
- "onPointerMove": handle_pointer_move,
+ "on_pointer_move": handle_pointer_move,
"style": {
"position": "relative",
"height": "200px",
"width": "100%",
- "backgroundColor": "white",
+ "background_color": "white",
},
},
html.div(
{
"style": {
"position": "absolute",
- "backgroundColor": "red",
- "borderRadius": "50%",
+ "background_color": "red",
+ "border_radius": "50%",
"width": "20px",
"height": "20px",
"left": "-10px",
"top": "-10px",
"transform": f"translate({position['x']}px, {position['y']}px)",
- },
+ }
}
),
)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py
similarity index 78%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py
index 90885e7fe..8972ce74e 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/moving_dot_broken.py
@@ -1,6 +1,6 @@
# :linenos:
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -15,26 +15,26 @@ def handle_pointer_move(event):
return html.div(
{
- "onPointerMove": handle_pointer_move,
+ "on_pointer_move": handle_pointer_move,
"style": {
"position": "relative",
"height": "200px",
"width": "100%",
- "backgroundColor": "white",
+ "background_color": "white",
},
},
html.div(
{
"style": {
"position": "absolute",
- "backgroundColor": "red",
- "borderRadius": "50%",
+ "background_color": "red",
+ "border_radius": "50%",
"width": "20px",
"height": "20px",
"left": "-10px",
"top": "-10px",
"transform": f"translate({position['x']}px, {position['y']}px)",
- },
+ }
}
),
)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_remove.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_remove.py
similarity index 82%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/set_remove.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_remove.py
index 4c4905350..abe55a918 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_remove.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_remove.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -20,18 +20,18 @@ def handle_click(event):
[
html.div(
{
- "onClick": make_handle_click(index),
+ "on_click": make_handle_click(index),
"style": {
"height": "30px",
"width": "30px",
- "backgroundColor": (
+ "background_color": (
"black" if index in selected_indices else "white"
),
"outline": "1px solid grey",
"cursor": "pointer",
},
- },
- key=index,
+ "key": index,
+ }
)
for index in range(line_size)
],
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_update.py b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_update.py
similarity index 79%
rename from docs/source/adding-interactivity/dangers-of-mutability/_examples/set_update.py
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_update.py
index 9e1077cb0..27f170a42 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/_examples/set_update.py
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/_examples/set_update.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -17,18 +17,18 @@ def handle_click(event):
[
html.div(
{
- "onClick": make_handle_click(index),
+ "on_click": make_handle_click(index),
"style": {
"height": "30px",
"width": "30px",
- "backgroundColor": (
+ "background_color": (
"black" if index in selected_indices else "white"
),
"outline": "1px solid grey",
"cursor": "pointer",
},
- },
- key=index,
+ "key": index,
+ }
)
for index in range(line_size)
],
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/index.rst b/docs/source/guides/adding-interactivity/dangers-of-mutability/index.rst
similarity index 94%
rename from docs/source/adding-interactivity/dangers-of-mutability/index.rst
rename to docs/source/guides/adding-interactivity/dangers-of-mutability/index.rst
index 80a4e6a04..bcac79e18 100644
--- a/docs/source/adding-interactivity/dangers-of-mutability/index.rst
+++ b/docs/source/guides/adding-interactivity/dangers-of-mutability/index.rst
@@ -2,7 +2,7 @@ Dangers of Mutability
=====================
While state can hold any type of value, you should be careful to avoid directly
-modifying objects that you declare as state with IDOM. In other words, you must not
+modifying objects that you declare as state with ReactPy. In other words, you must not
:ref:`"mutate" ` values which are held as state. Rather, to change
these values you should use new ones or create copies.
@@ -42,8 +42,8 @@ facilitate change:
values are equivalent with the ``==`` or ``!=`` operators.
Thus far, all the values we've been working with have been immutable. These include
-:class:`int`, :class:`float`, :class:`str`, and :class:`bool` values. As a result, we've
-have not had to consider the consiquences of mutations.
+:class:`int`, :class:`float`, :class:`str`, and :class:`bool` values. As a result, we
+have not had to consider the consequences of mutations.
.. _Why Avoid Mutation:
@@ -51,13 +51,13 @@ have not had to consider the consiquences of mutations.
Why Avoid Mutation?
-------------------
-Unfortunately, IDOM does not understand that when a value is mutated, it may have
+Unfortunately, ReactPy does not understand that when a value is mutated, it may have
changed. As a result, mutating values will not trigger re-renders. Thus, you must be
-careful to avoid mutation whenever you want IDOM to re-render a component. For example,
+careful to avoid mutation whenever you want ReactPy to re-render a component. For example,
the intention of the code below is to make the red dot move when you touch or hover over
the preview area. However it doesn't - the dot remains stationary:
-.. idom:: _examples/moving_dot_broken
+.. reactpy:: _examples/moving_dot_broken
The problem is with this section of code:
@@ -68,7 +68,7 @@ The problem is with this section of code:
:lineno-start: 13
This code mutates the ``position`` dictionary from the prior render instead of using the
-state variable's associated state setter. Without calling setter IDOM has no idea that
+state variable's associated state setter. Without calling setter ReactPy has no idea that
the variable's data has been modified. While it can be possible to get away with
mutating state variables, it's highly dicsouraged. Doing so can cause strange and
unpredictable behavior. As a result, you should always treat the data within a state
@@ -80,7 +80,7 @@ call it by passing a *new* dictionary with the values for the next render. Notic
by making these alterations to the code, that the dot now follows your pointer when
you touch or hover over the preview:
-.. idom:: _examples/moving_dot
+.. reactpy:: _examples/moving_dot
.. dropdown:: Local mutation can be alright
@@ -208,7 +208,7 @@ updating user information with a preview of the currently entered data. We can
accomplish this using `"unpacking" `__ with
the ``**`` syntax:
-.. idom:: _examples/dict_update
+.. reactpy:: _examples/dict_update
.. _removing-dictionary-items:
@@ -249,7 +249,7 @@ set of keys. One way to do this is with a dictionary comprehension. The example
shows an interface where you're able to enter a new term and definition. Once added,
you can click a delete button to remove the term and definition:
-.. idom:: _examples/dict_remove
+.. reactpy:: _examples/dict_remove
Working with Lists
@@ -349,7 +349,7 @@ the items we want to append instead. There are several ways to do this for one o
values however it's often simplest to use `"unpacking"
`__ with the ``*`` syntax.
-.. idom:: _examples/list_insert
+.. reactpy:: _examples/list_insert
.. _removing-list-items:
@@ -378,7 +378,7 @@ not quite as clean. You must select the portion the list prior to the item which
be removed (``l[:index]``) and the portion after the item (``l[index + 1:]``) and add
them together:
-.. idom:: _examples/list_remove
+.. reactpy:: _examples/list_remove
.. _replacing-list-items:
@@ -409,7 +409,7 @@ must select the portion before and after the item in question. But this time, in
of adding those two selections together, you must insert that values you want to replace
between them:
-.. idom:: _examples/list_replace
+.. reactpy:: _examples/list_replace
.. _re-ordering-list-items:
@@ -441,7 +441,7 @@ list object, you should use the builtin functions :func:`sorted` and :func:`reve
and pass the resulting iterator into the :class:`list` constructor to create a sorted
or reversed copy of the given list:
-.. idom:: _examples/list_re_order
+.. reactpy:: _examples/list_re_order
Working with Sets
@@ -512,7 +512,7 @@ or operator ``|`` serves as a succinct way to compute the union of two sets. How
you should be careful to not use an in-place assignment with this operator as that will
(counterintuitively) mutate the original set rather than creating a new one.
-.. idom:: _examples/set_update
+.. reactpy:: _examples/set_update
.. _removing-set-items:
@@ -531,7 +531,7 @@ Removing Set Items
s.difference_update(values)
s -= values # "in-place" operators mutate!
- s.symetric_difference_update(values)
+ s.symmetric_difference_update(values)
s ^= values # "in-place" operators mutate!
s.intersection_update(values)
@@ -547,7 +547,7 @@ Removing Set Items
s.difference(values)
s - values
- s.symetric_difference(values)
+ s.symmetric_difference(values)
s ^ values
s.intersection(values)
@@ -558,7 +558,7 @@ methods to return new sets without mutating them. As before when :ref:`adding se
you need to avoid using the inline assignment operators since that will
(counterintuitively) mutate the original set rather than given you a new one:
-.. idom:: _examples/set_remove
+.. reactpy:: _examples/set_remove
Useful Packages
diff --git a/docs/source/adding-interactivity/index.rst b/docs/source/guides/adding-interactivity/index.rst
similarity index 81%
rename from docs/source/adding-interactivity/index.rst
rename to docs/source/guides/adding-interactivity/index.rst
index a09db3f51..af84fab88 100644
--- a/docs/source/adding-interactivity/index.rst
+++ b/docs/source/guides/adding-interactivity/index.rst
@@ -56,15 +56,15 @@ Adding Interactivity
Section 1: Responding to Events
-------------------------------
-IDOM lets you add event handlers to your parts of the interface. This means that you can
+ReactPy lets you add event handlers to your parts of the interface. This means that you can
define synchronous or asynchronous functions that are triggered when a particular user
-interaction occurs like clicking, hovering, of focusing on form inputs, and more.
+interaction occurs like clicking, hovering, focusing on form inputs, and more.
-.. idom:: responding-to-events/_examples/button_prints_message
+.. reactpy:: responding-to-events/_examples/button_prints_message
It may feel weird to define a function within a function like this, but doing so allows
the ``handle_event`` function to access information from within the scope of the
-component. That's important if you want to use any arguments that may have beend passed
+component. That's important if you want to use any arguments that may have been passed
your component in the handler.
.. card::
@@ -85,16 +85,16 @@ Components often need to change whatâs on the screen as a result of an interac
example, typing into the form should update the input field, clicking a âCommentâ button
should bring up a text input field, clicking âBuyâ should put a product in the shopping
cart. Components need to ârememberâ things like the current input value, the current
-image, the shopping cart. In IDOM, this kind of component-specific memory is created and
+image, the shopping cart. In ReactPy, this kind of component-specific memory is created and
updated with a "hook" called ``use_state()`` that creates a **state variable** and
**state setter** respectively:
-.. idom:: components-with-state/_examples/adding_state_variable
+.. reactpy:: components-with-state/_examples/adding_state_variable
-In IDOM, ``use_state``, as well as any other function whose name starts with ``use``, is
-called a "hook". These are special functions that should only be called while IDOM is
+In ReactPy, ``use_state``, as well as any other function whose name starts with ``use``, is
+called a "hook". These are special functions that should only be called while ReactPy is
:ref:`rendering `. They let you "hook into" the different
-capabilities of IDOM's components of which ``use_state`` is just one (well get into the
+capabilities of ReactPy's components of which ``use_state`` is just one (well get into the
other :ref:`later `).
.. card::
@@ -111,7 +111,7 @@ Section 3: State as a Snapshot
------------------------------
As we :ref:`learned earlier `, state setters behave a little
-differently than you might exepct at first glance. Instead of updating your current
+differently than you might expect at first glance. Instead of updating your current
handle on the setter's corresponding variable, it schedules a re-render of the component
which owns the state.
@@ -122,7 +122,7 @@ which owns the state.
set_count(count + 1) # schedule a re-render where count is 1
print(count) # still prints: 0
-This behavior of IDOM means that each render of a component is like taking a snapshot of
+This behavior of ReactPy means that each render of a component is like taking a snapshot of
the UI based on the component's state at that time. Treating state in this way can help
reduce subtle bugs. For instance, in the code below there's a simple chat app with a
message input and recipient selector. The catch is that the message actually gets sent 5
@@ -130,15 +130,15 @@ seconds after the "Send" button is clicked. So what would happen if we changed t
recipient between the time the "Send" button was clicked and the moment the message is
actually sent?
-.. idom:: state-as-a-snapshot/_examples/print_chat_message
+.. reactpy:: state-as-a-snapshot/_examples/print_chat_message
As it turns out, changing the message recipient after pressing send does not change
-where the message ulitmately goes. However, one could imagine a bug where the recipient
+where the message ultimately goes. However, one could imagine a bug where the recipient
of a message is determined at the time the message is sent rather than at the time the
"Send" button it clicked. Thus changing the recipient after pressing send would change
where the message got sent.
-In many cases, IDOM avoids this class of bug entirely because it treats state as a
+In many cases, ReactPy avoids this class of bug entirely because it treats state as a
snapshot.
.. card::
@@ -159,10 +159,10 @@ changes to state only take effect in the next render, not in the current one. Fu
changes to state are batched, calling a particular state setter 3 times won't trigger 3
renders, it will only trigger 1. This means that multiple state assignments are batched
- so long as the event handler is synchronous (i.e. the event handler is not an
-``async`` function), IDOM waits until all the code in an event handler has run before
+``async`` function), ReactPy waits until all the code in an event handler has run before
processing state and starting the next render:
-.. idom:: multiple-state-updates/_examples/set_color_3_times
+.. reactpy:: multiple-state-updates/_examples/set_color_3_times
Sometimes though, you need to update a state variable more than once before the next
render. In these cases, instead of having updates batched, you instead want them to be
@@ -172,7 +172,7 @@ To accomplish this, instead of passing the next state value directly (e.g.
``compute_new_state(old_state)`` to the state setter (e.g.
``set_state(compute_new_state)``):
-.. idom:: multiple-state-updates/_examples/set_state_function
+.. reactpy:: multiple-state-updates/_examples/set_state_function
.. card::
:link: multiple-state-updates/index
@@ -188,17 +188,17 @@ Section 5: Dangers of Mutability
--------------------------------
While state can hold any type of value, you should be careful to avoid directly
-modifying objects that you declare as state with IDOM. In other words, you must not
+modifying objects that you declare as state with ReactPy. In other words, you must not
:ref:`"mutate" ` values which are held as state. Rather, to change
these values you should use new ones or create copies.
-This is because IDOM does not understand that when a value is mutated, it may have
+This is because ReactPy does not understand that when a value is mutated, it may have
changed. As a result, mutating values will not trigger re-renders. Thus, you must be
-careful to avoid mutation whenever you want IDOM to re-render a component. For example,
+careful to avoid mutation whenever you want ReactPy to re-render a component. For example,
instead of mutating dictionaries to update their items you should instead create a
copy that contains the desired changes:
-.. idom:: dangers-of-mutability/_examples/dict_update
+.. reactpy:: dangers-of-mutability/_examples/dict_update
.. card::
:link: dangers-of-mutability/index
diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py
similarity index 70%
rename from docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py
rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py
index 0c000477e..e53c5b1ad 100644
--- a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py
+++ b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_count_updater.py
@@ -1,6 +1,6 @@
import asyncio
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -13,7 +13,7 @@ async def handle_click(event):
return html.div(
html.h1(number),
- html.button({"onClick": handle_click}, "Increment"),
+ html.button({"on_click": handle_click}, "Increment"),
)
diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py
similarity index 68%
rename from docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py
rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py
index 024df12e7..bb64724f1 100644
--- a/docs/source/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py
+++ b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/delay_before_set_count.py
@@ -1,6 +1,6 @@
import asyncio
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -13,7 +13,7 @@ async def handle_click(event):
return html.div(
html.h1(number),
- html.button({"onClick": handle_click}, "Increment"),
+ html.button({"on_click": handle_click}, "Increment"),
)
diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py
similarity index 59%
rename from docs/source/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py
rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py
index e755c35b9..59d7d0f20 100644
--- a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py
+++ b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_color_3_times.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
@component
@@ -15,10 +15,11 @@ def handle_reset(event):
return html.div(
html.button(
- {"onClick": handle_click, "style": {"backgroundColor": color}}, "Set Color"
+ {"on_click": handle_click, "style": {"background_color": color}},
+ "Set Color",
),
html.button(
- {"onClick": handle_reset, "style": {"backgroundColor": color}}, "Reset"
+ {"on_click": handle_reset, "style": {"background_color": color}}, "Reset"
),
)
diff --git a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_state_function.py b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_state_function.py
similarity index 74%
rename from docs/source/adding-interactivity/multiple-state-updates/_examples/set_state_function.py
rename to docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_state_function.py
index ec3193de9..56bbe80e3 100644
--- a/docs/source/adding-interactivity/multiple-state-updates/_examples/set_state_function.py
+++ b/docs/source/guides/adding-interactivity/multiple-state-updates/_examples/set_state_function.py
@@ -1,4 +1,4 @@
-from idom import component, html, run, use_state
+from reactpy import component, html, run, use_state
def increment(old_number):
@@ -17,7 +17,7 @@ def handle_click(event):
return html.div(
html.h1(number),
- html.button({"onClick": handle_click}, "Increment"),
+ html.button({"on_click": handle_click}, "Increment"),
)
diff --git a/docs/source/adding-interactivity/multiple-state-updates/index.rst b/docs/source/guides/adding-interactivity/multiple-state-updates/index.rst
similarity index 87%
rename from docs/source/adding-interactivity/multiple-state-updates/index.rst
rename to docs/source/guides/adding-interactivity/multiple-state-updates/index.rst
index 73524e173..bc3245d7e 100644
--- a/docs/source/adding-interactivity/multiple-state-updates/index.rst
+++ b/docs/source/guides/adding-interactivity/multiple-state-updates/index.rst
@@ -10,21 +10,21 @@ Batched Updates
---------------
As we learned :ref:`previously `, state variables remain fixed
-inside each render as if state were a snapshot taken at the begining of each render.
+inside each render as if state were a snapshot taken at the beginning of each render.
This is why, in the example below, even though it might seem like clicking the
"Increment" button would cause the ``number`` to increase by ``3``, it only does by
``1``:
-.. idom:: ../state-as-a-snapshot/_examples/set_counter_3_times
+.. reactpy:: ../state-as-a-snapshot/_examples/set_counter_3_times
The reason this happens is because, so long as the event handler is synchronous (i.e.
-the event handler is not an ``async`` function), IDOM waits until all the code in an
+the event handler is not an ``async`` function), ReactPy waits until all the code in an
event handler has run before processing state and starting the next render. Thus, it's
the last call to a given state setter that matters. In the example below, even though we
set the color of the button to ``"orange"`` and then ``"pink"`` before ``"blue"``,
-the color does not quickly flash orange and pink before blue - it alway remains blue:
+the color does not quickly flash orange and pink before blue - it always remains blue:
-.. idom:: _examples/set_color_3_times
+.. reactpy:: _examples/set_color_3_times
This behavior let's you make multiple state changes without triggering unnecessary
renders or renders with inconsistent state where only some of the variables have been
@@ -33,13 +33,13 @@ handlers have finished running.
.. note::
- For asynchronous event handlers, IDOM will not render until you ``await`` something.
+ For asynchronous event handlers, ReactPy will not render until you ``await`` something.
As we saw in :ref:`prior examples `, if you introduce
an asynchronous delay to an event handler after changing state, renders may take
place before the remainder of the event handler completes. However, state variables
within handlers, even async ones, always remains static.
-This behavior of IDOM to "batch" state changes that take place inside a single event
+This behavior of ReactPy to "batch" state changes that take place inside a single event
handler, do not extend across event handlers. In other words, distinct events will
always produce distinct renders. To give an example, if clicking a button increments a
counter by one, no matter how fast the user clicks, the view will never jump from 1 to 3
@@ -77,9 +77,9 @@ In our case, ``new_state = old_state + 1``. So we might define:
Which we can use to replace ``set_number(number + 1)`` with ``set_number(increment)``:
-.. idom:: _examples/set_state_function
+.. reactpy:: _examples/set_state_function
-The way to think about how IDOM runs though this series of ``set_state(increment)``
+The way to think about how ReactPy runs though this series of ``set_state(increment)``
calls is to imagine that each one updates the internally managed state with its return
value, then that return value is being passed to the next updater function. Ultimately,
this is functionally equivalent to the following:
@@ -94,14 +94,14 @@ introduced a delay before ``set_number(number + 1)``. What would happen if we cl
the "Increment" button more than once before the delay in the first triggered event
completed?
-.. idom:: _examples/delay_before_set_count
+.. reactpy:: _examples/delay_before_set_count
From an :ref:`earlier lesson `, we learned that introducing
delays do not change the fact that state variables do not change until the next render.
As a result, despite clicking many times before the delay completes, the ``number`` only
increments by one. To solve this we can use updater functions:
-.. idom:: _examples/delay_before_count_updater
+.. reactpy:: _examples/delay_before_count_updater
Now when you click the "Increment" button, each click, though delayed, corresponds to
``number`` being increased. This is because the ``old_number`` in the updater function
diff --git a/docs/source/guides/adding-interactivity/responding-to-events/_examples/audio_player.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/audio_player.py
new file mode 100644
index 000000000..82826c50d
--- /dev/null
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/audio_player.py
@@ -0,0 +1,21 @@
+import json
+
+import reactpy
+
+
+@reactpy.component
+def PlayDinosaurSound():
+ event, set_event = reactpy.hooks.use_state(None)
+ return reactpy.html.div(
+ reactpy.html.audio(
+ {
+ "controls": True,
+ "on_time_update": lambda e: set_event(e),
+ "src": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
+ }
+ ),
+ reactpy.html.pre(json.dumps(event, indent=2)),
+ )
+
+
+reactpy.run(PlayDinosaurSound)
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_async_handlers.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_async_handlers.py
similarity index 76%
rename from docs/source/adding-interactivity/responding-to-events/_examples/button_async_handlers.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_async_handlers.py
index a355f6142..992641e00 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/button_async_handlers.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_async_handlers.py
@@ -1,6 +1,6 @@
import asyncio
-from idom import component, html, run
+from reactpy import component, html, run
@component
@@ -9,7 +9,7 @@ async def handle_event(event):
await asyncio.sleep(delay)
print(message)
- return html.button({"onClick": handle_event}, message)
+ return html.button({"on_click": handle_event}, message)
@component
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_does_nothing.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_does_nothing.py
similarity index 68%
rename from docs/source/adding-interactivity/responding-to-events/_examples/button_does_nothing.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_does_nothing.py
index e26e770d2..ea8313263 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/button_does_nothing.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_does_nothing.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py
similarity index 83%
rename from docs/source/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py
index 4de22a024..e5276bef3 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_handler_as_arg.py
@@ -1,9 +1,9 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
def Button(display_text, on_click):
- return html.button({"onClick": on_click}, display_text)
+ return html.button({"on_click": on_click}, display_text)
@component
diff --git a/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_event.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_event.py
new file mode 100644
index 000000000..38638db4b
--- /dev/null
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_event.py
@@ -0,0 +1,12 @@
+from reactpy import component, html, run
+
+
+@component
+def Button():
+ def handle_event(event):
+ print(event)
+
+ return html.button({"on_click": handle_event}, "Click me!")
+
+
+run(Button)
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/button_prints_message.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_message.py
similarity index 70%
rename from docs/source/adding-interactivity/responding-to-events/_examples/button_prints_message.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_message.py
index f5ee69f80..56118a57f 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/button_prints_message.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/button_prints_message.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
@@ -6,7 +6,7 @@ def PrintButton(display_text, message_text):
def handle_event(event):
print(message_text)
- return html.button({"onClick": handle_event}, display_text)
+ return html.button({"on_click": handle_event}, display_text)
@component
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py
similarity index 70%
rename from docs/source/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py
index 7e8ef9938..d3f0941bd 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/prevent_default_event_actions.py
@@ -1,4 +1,4 @@
-from idom import component, event, html, run
+from reactpy import component, event, html, run
@component
@@ -7,7 +7,7 @@ def DoNotChangePages():
html.p("Normally clicking this link would take you to a new page"),
html.a(
{
- "onClick": event(lambda event: None, prevent_default=True),
+ "on_click": event(lambda event: None, prevent_default=True),
"href": "https://google.com",
},
"https://google.com",
diff --git a/docs/source/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py b/docs/source/guides/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py
similarity index 61%
rename from docs/source/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py
rename to docs/source/guides/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py
index e87bae026..41c575042 100644
--- a/docs/source/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py
+++ b/docs/source/guides/adding-interactivity/responding-to-events/_examples/stop_event_propagation.py
@@ -1,4 +1,4 @@
-from idom import component, event, hooks, html, run
+from reactpy import component, event, hooks, html, run
@component
@@ -9,24 +9,28 @@ def DivInDiv():
div_in_div = html.div(
{
- "onClick": lambda event: set_outer_count(outer_count + 1),
- "style": {"height": "100px", "width": "100px", "backgroundColor": "red"},
+ "on_click": lambda event: set_outer_count(outer_count + 1),
+ "style": {"height": "100px", "width": "100px", "background_color": "red"},
},
html.div(
{
- "onClick": event(
+ "on_click": event(
lambda event: set_inner_count(inner_count + 1),
stop_propagation=stop_propagatation,
),
- "style": {"height": "50px", "width": "50px", "backgroundColor": "blue"},
- },
+ "style": {
+ "height": "50px",
+ "width": "50px",
+ "background_color": "blue",
+ },
+ }
),
)
return html.div(
html.button(
- {"onClick": lambda event: set_stop_propagatation(not stop_propagatation)},
- "Toggle Propogation",
+ {"on_click": lambda event: set_stop_propagatation(not stop_propagatation)},
+ "Toggle Propagation",
),
html.pre(f"Will propagate: {not stop_propagatation}"),
html.pre(f"Inner click count: {inner_count}"),
diff --git a/docs/source/adding-interactivity/responding-to-events/index.rst b/docs/source/guides/adding-interactivity/responding-to-events/index.rst
similarity index 77%
rename from docs/source/adding-interactivity/responding-to-events/index.rst
rename to docs/source/guides/adding-interactivity/responding-to-events/index.rst
index 3b3033bf6..89f567ca0 100644
--- a/docs/source/adding-interactivity/responding-to-events/index.rst
+++ b/docs/source/guides/adding-interactivity/responding-to-events/index.rst
@@ -1,7 +1,7 @@
Responding to Events
====================
-IDOM lets you add event handlers to your parts of the interface. These events handlers
+ReactPy lets you add event handlers to your parts of the interface. These events handlers
are functions which can be assigned to a part of a UI such that, when a user iteracts
with the interface, those functions get triggered. Examples of interaction include
clicking, hovering, of focusing on form inputs, and more.
@@ -12,7 +12,7 @@ Adding Event Handlers
To start out we'll just display a button that, for the moment, doesn't do anything:
-.. idom:: _examples/button_does_nothing
+.. reactpy:: _examples/button_does_nothing
To add an event handler to this button we'll do three things:
@@ -20,19 +20,19 @@ To add an event handler to this button we'll do three things:
2. Add logic to ``handle_event`` that will print the ``event`` it receives to the console.
3. Add an ``"onClick": handle_event`` attribute to the ``
-What this shows is that you can recreate the same HTML layouts with IDOM using functions
-from the :mod:`idom.html` module. These function share the same names as their
+What this shows is that you can recreate the same HTML layouts with ReactPy using functions
+from the :mod:`reactpy.html` module. These function share the same names as their
corresponding HTML tags. For instance, the ```` element above has a similarly named
-:func:`~idom.html.h1` function. With that said, while the code above looks similar, it's
+:func:`~reactpy.html.h1` function. With that said, while the code above looks similar, it's
not very useful because we haven't captured the results from these function calls in a
variable. To do this we need to wrap up the layout above into a single
-:func:`~idom.html.div` and assign it to a variable:
+:func:`~reactpy.html.div` and assign it to a variable:
.. testcode::
@@ -73,49 +71,61 @@ Adding HTML Attributes
----------------------
That's all well and good, but there's more to HTML than just text. What if we wanted to
-display an image? In HTMl we'd use the `` element and add attributes to it order
+display an image? In HTMl we'd use the ```` element and add attributes to it order
to specify a URL to its ``src`` and use some ``style`` to modify and position it:
.. code-block:: html
-In IDOM we add these attributes to elements using dictionaries. There are some notable
-differences though. The biggest being the fact that all names in IDOM use ``camelCase``
-instead of dash-sepearted words. For example, ``margin-left`` becomes ``marginLeft``.
-Additionally, instead of specifying ``style`` using a string, we use a dictionary:
+In ReactPy we add these attributes to elements using a dictionary:
.. testcode::
html.img(
{
"src": "https://picsum.photos/id/237/500/300",
- "style": {"width": "50%", "marginLeft": "25%"},
+ "class_name": "img-fluid",
+ "style": {"width": "50%", "margin_left": "25%"},
"alt": "Billie Holiday",
}
)
.. raw:: html
+
+There are some notable differences. First, all names in ReactPy use ``snake_case`` instead
+of dash-separated words. For example, ``tabindex`` and ``margin-left`` become
+``tab_index`` and ``margin_left`` respectively. Second, instead of using a string to
+specify the ``style`` attribute, we use a dictionary to describe the CSS properties we
+want to apply to an element. This is done to avoid having to escape quotes and other
+characters in the string. Finally, the ``class`` attribute is renamed to ``class_name``
+to avoid conflicting with the ``class`` keyword in Python.
+
+For full list of supported attributes and differences from HTML, see the
+:ref:`HTML Attributes` reference.
----------
.. card::
- :link: /understanding-idom/representing-html
+ :link: /guides/understanding-reactpy/representing-html
:link-type: doc
:octicon:`book` Read More
^^^^^^^^^^^^^^^^^^^^^^^^^
- Dive into the data structures IDOM uses to represent HTML
+ Dive into the data structures ReactPy uses to represent HTML
diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/guides/creating-interfaces/index.rst
similarity index 72%
rename from docs/source/creating-interfaces/index.rst
rename to docs/source/guides/creating-interfaces/index.rst
index 77f9fd4fc..78466eaef 100644
--- a/docs/source/creating-interfaces/index.rst
+++ b/docs/source/guides/creating-interfaces/index.rst
@@ -4,9 +4,9 @@ Creating Interfaces
.. toctree::
:hidden:
- html-with-idom
- your-first-components
- rendering-data
+ html-with-reactpy/index
+ your-first-components/index
+ rendering-data/index
.. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
:color: info
@@ -15,39 +15,39 @@ Creating Interfaces
.. grid:: 1 2 2 2
- .. grid-item-card:: :octicon:`code-square` HTML with IDOM
- :link: html-with-idom
+ .. grid-item-card:: :octicon:`code-square` HTML with ReactPy
+ :link: html-with-reactpy/index
:link-type: doc
Construct HTML layouts from the basic units of user interface functionality.
.. grid-item-card:: :octicon:`package` Your First Components
- :link: your-first-components
+ :link: your-first-components/index
:link-type: doc
Define reusable building blocks that it easier to construct complex
interfaces.
.. grid-item-card:: :octicon:`database` Rendering Data
- :link: rendering-data
+ :link: rendering-data/index
:link-type: doc
Use data to organize and render HTML elements and components.
-IDOM is a Python package for making user interfaces (UI). These interfaces are built
-from small elements of functionality like buttons text and images. IDOM allows you to
+ReactPy is a Python package for making user interfaces (UI). These interfaces are built
+from small elements of functionality like buttons text and images. ReactPy allows you to
combine these elements into reusable, nestable :ref:`"components" `. In the sections that follow you'll learn how these UI elements are created
and organized into components. Then, you'll use components to customize and
conditionally display more complex UIs.
-Section 1: HTML with IDOM
--------------------------
+Section 1: HTML with ReactPy
+----------------------------
-In a typical Python-base web application the resonsibility of defining the view along
+In a typical Python-base web application the responsibility of defining the view along
with its backing data and logic are distributed between a client and server
-respectively. With IDOM, both these tasks are centralized in a single place. The most
+respectively. With ReactPy, both these tasks are centralized in a single place. The most
foundational pilar of this capability is formed by allowing HTML interfaces to be
constructed in Python. Let's consider the HTML sample below:
@@ -59,11 +59,11 @@ constructed in Python. Let's consider the HTML sample below:
Share it with the world!
-To recreate the same thing in IDOM you would write:
+To recreate the same thing in ReactPy you would write:
.. code-block::
- from idom import html
+ from reactpy import html
html.div(
html.h1("My Todo List"),
@@ -75,7 +75,7 @@ To recreate the same thing in IDOM you would write:
)
.. card::
- :link: html-with-idom
+ :link: html-with-reactpy/index
:link-type: doc
:octicon:`book` Read More
@@ -87,17 +87,17 @@ To recreate the same thing in IDOM you would write:
Section 2: Your First Components
--------------------------------
-The next building block in our journey with IDOM are components. At their core,
-components are just a normal Python functions that return :ref:`HTML `.
+The next building block in our journey with ReactPy are components. At their core,
+components are just a normal Python functions that return :ref:`HTML `.
The one special thing about them that we'll concern ourselves with now, is that to
create them we need to add an ``@component`` `decorator
`__. To see what this looks like in
practice we'll quickly make a ``Photo`` component:
-.. idom:: _examples/simple_photo
+.. reactpy:: your-first-components/_examples/simple_photo
.. card::
- :link: your-first-components
+ :link: your-first-components/index
:link-type: doc
:octicon:`book` Read More
@@ -112,14 +112,14 @@ Section 3: Rendering Data
The last pillar of knowledge you need before you can start making :ref:`interactive
interfaces ` is the ability to render sections of the UI given a
collection of data. This will require you to understand how elements which are derived
-from data in this way must be orgnized with :ref:`"keys" `.
+from data in this way must be organized with :ref:`"keys" `.
One case where we might want to do this is if items in a todo list come from a list of
data that we want to sort and filter:
-.. idom:: _examples/todo_list_with_keys
+.. reactpy:: rendering-data/_examples/todo_list_with_keys
.. card::
- :link: rendering-data
+ :link: rendering-data/index
:link-type: doc
:octicon:`book` Read More
diff --git a/docs/source/creating-interfaces/_examples/sorted_and_filtered_todo_list.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py
similarity index 89%
rename from docs/source/creating-interfaces/_examples/sorted_and_filtered_todo_list.py
rename to docs/source/guides/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py
index 28708416e..8be2b5f30 100644
--- a/docs/source/creating-interfaces/_examples/sorted_and_filtered_todo_list.py
+++ b/docs/source/guides/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
@@ -6,7 +6,7 @@ def DataList(items, filter_by_priority=None, sort_by_priority=False):
if filter_by_priority is not None:
items = [i for i in items if i["priority"] <= filter_by_priority]
if sort_by_priority:
- items = list(sorted(items, key=lambda i: i["priority"]))
+ items = sorted(items, key=lambda i: i["priority"])
list_item_elements = [html.li(i["text"]) for i in items]
return html.ul(list_item_elements)
diff --git a/docs/source/creating-interfaces/_examples/todo_from_list.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_from_list.py
similarity index 92%
rename from docs/source/creating-interfaces/_examples/todo_from_list.py
rename to docs/source/guides/creating-interfaces/rendering-data/_examples/todo_from_list.py
index 474c78770..85ba1d79d 100644
--- a/docs/source/creating-interfaces/_examples/todo_from_list.py
+++ b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_from_list.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/creating-interfaces/_examples/todo_list_with_keys.py b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py
similarity index 83%
rename from docs/source/creating-interfaces/_examples/todo_list_with_keys.py
rename to docs/source/guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py
index 5a173e1e0..8afd2ae55 100644
--- a/docs/source/creating-interfaces/_examples/todo_list_with_keys.py
+++ b/docs/source/guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
@@ -6,8 +6,8 @@ def DataList(items, filter_by_priority=None, sort_by_priority=False):
if filter_by_priority is not None:
items = [i for i in items if i["priority"] <= filter_by_priority]
if sort_by_priority:
- items = list(sorted(items, key=lambda i: i["priority"]))
- list_item_elements = [html.li(i["text"], key=i["id"]) for i in items]
+ items = sorted(items, key=lambda i: i["priority"])
+ list_item_elements = [html.li({"key": i["id"]}, i["text"]) for i in items]
return html.ul(list_item_elements)
diff --git a/docs/source/creating-interfaces/rendering-data.rst b/docs/source/guides/creating-interfaces/rendering-data/index.rst
similarity index 89%
rename from docs/source/creating-interfaces/rendering-data.rst
rename to docs/source/guides/creating-interfaces/rendering-data/index.rst
index d10aed9c3..620426142 100644
--- a/docs/source/creating-interfaces/rendering-data.rst
+++ b/docs/source/guides/creating-interfaces/rendering-data/index.rst
@@ -40,7 +40,7 @@ We could then take this list and "render" it into a series of ``
`` elements:
.. testcode::
- from idom import html
+ from reactpy import html
list_item_elements = [html.li(text) for text in tasks]
@@ -52,7 +52,7 @@ This list of elements can then be passed into a parent ``
`` element:
The last thing we have to do is return this from a component:
-.. idom:: _examples/todo_from_list
+.. reactpy:: _examples/todo_from_list
Filtering and Sorting Elements
@@ -76,14 +76,10 @@ priority. Thus, we need to change the data structure we're using to represent ou
]
With this we can now imaging writing some filtering and sorting logic using Python's
-:func:`filter` and :func:`sorted` functions respecitvely. We'll do this by only
+:func:`filter` and :func:`sorted` functions respectively. We'll do this by only
displaying items whose ``priority`` is less than or equal to some ``filter_by_priority``
and then ordering the elements based on the ``priority``:
-.. testcode::
-
- x = 1
-
.. testcode::
filter_by_priority = 1
@@ -105,13 +101,18 @@ and then ordering the elements based on the ``priority``:
We could then add this code to our ``DataList`` component:
-.. idom:: _examples/sorted_and_filtered_todo_list
+.. warning::
+
+ The code below produces a bunch of warnings! Be sure to read the
+ :ref:`next section ` to find out why.
+
+.. reactpy:: _examples/sorted_and_filtered_todo_list
Organizing Items With Keys
--------------------------
-If you run the examples above :ref:`in debug mode ` you'll
+If you run the examples above :ref:`in debug mode ` you'll
see the server log a bunch of errors that look something like:
.. code-block:: text
@@ -135,20 +136,19 @@ structure even further to include a unique ID for each item in our todo list:
{"id": 7, "text": "Read a book", "priority": 1},
]
-Then, as we're constructing our ``
`` elements we'll pass in a ``key`` argument to
-the element constructor:
+Then, as we're constructing our ``
`` elements we'll declare a ``key`` attribute:
.. code-block::
- list_item_elements = [html.li(t["text"], key=t["id"]) for t in tasks]
+ list_item_elements = [html.li({"key": t["id"]}, t["text"]) for t in tasks]
-This ``key`` tells IDOM which ``
`` element corresponds to which item of data in our
+This ``key`` tells ReactPy which ``
`` element corresponds to which item of data in our
``tasks`` list. This becomes important if the order or number of items in your list can
change. In our case, if we decided to change whether we want to ``filter_by_priority``
or ``sort_by_priority`` the items in our ``
`` element would change. Given this,
here's how we'd change our component:
-.. idom:: _examples/todo_list_with_keys
+.. reactpy:: _examples/todo_list_with_keys
Keys for Components
@@ -161,7 +161,7 @@ exact same way that it does for standard HTML elements:
.. testcode::
- from idom import component
+ from reactpy import component
@component
@@ -189,7 +189,7 @@ exact same way that it does for standard HTML elements:
.. testcode::
- from idom import component
+ from reactpy import component
@component
def FunctionWithKeyParam(key):
@@ -231,7 +231,7 @@ with the correct UI element.
html.ul([html.li(data["text"], key=data["id"]) for data in data_2]),
)
-.. dropdown:: Keys must be unique amonst siblings
+.. dropdown:: Keys must be unique amongst siblings
:color: danger
Keys must be unique among siblings.
@@ -288,10 +288,10 @@ use for each ``key``?
.. card::
- :link: /understanding-idom/why-idom-needs-keys
+ :link: /guides/understanding-reactpy/why-reactpy-needs-keys
:link-type: doc
:octicon:`book` Read More
^^^^^^^^^^^^^^^^^^^^^^^^^
- Learn about why IDOM needs keys in the first place.
+ Learn about why ReactPy needs keys in the first place.
diff --git a/docs/source/creating-interfaces/_examples/bad_conditional_todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py
similarity index 91%
rename from docs/source/creating-interfaces/_examples/bad_conditional_todo_list.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py
index a5de11f77..1ed3268b6 100644
--- a/docs/source/creating-interfaces/_examples/bad_conditional_todo_list.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/creating-interfaces/_examples/good_conditional_todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py
similarity index 79%
rename from docs/source/creating-interfaces/_examples/good_conditional_todo_list.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py
index 64d6f6813..cd9ab6fc0 100644
--- a/docs/source/creating-interfaces/_examples/good_conditional_todo_list.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py
@@ -1,9 +1,9 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
def Item(name, done):
- return html.li(name, "" if done else " â")
+ return html.li(name, " â" if done else "")
@component
diff --git a/docs/source/creating-interfaces/_examples/nested_photos.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/nested_photos.py
similarity index 89%
rename from docs/source/creating-interfaces/_examples/nested_photos.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/nested_photos.py
index 4c512b7e6..96f8531d3 100644
--- a/docs/source/creating-interfaces/_examples/nested_photos.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/nested_photos.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/creating-interfaces/_examples/parametrized_photos.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/parametrized_photos.py
similarity index 78%
rename from docs/source/creating-interfaces/_examples/parametrized_photos.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/parametrized_photos.py
index aeea41589..665dd8c86 100644
--- a/docs/source/creating-interfaces/_examples/parametrized_photos.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/parametrized_photos.py
@@ -1,11 +1,11 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
def Photo(alt_text, image_id):
return html.img(
{
- "src": f"https://picsum.photos/id/{image_id}/500/300",
+ "src": f"https://picsum.photos/id/{image_id}/500/200",
"style": {"width": "50%"},
"alt": alt_text,
}
diff --git a/docs/source/creating-interfaces/_examples/simple_photo.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/simple_photo.py
similarity index 83%
rename from docs/source/creating-interfaces/_examples/simple_photo.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/simple_photo.py
index c6b92c652..94fa6633f 100644
--- a/docs/source/creating-interfaces/_examples/simple_photo.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/simple_photo.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/creating-interfaces/_examples/todo_list.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/todo_list.py
similarity index 90%
rename from docs/source/creating-interfaces/_examples/todo_list.py
rename to docs/source/guides/creating-interfaces/your-first-components/_examples/todo_list.py
index 4f0053c4b..2ffd09261 100644
--- a/docs/source/creating-interfaces/_examples/todo_list.py
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/todo_list.py
@@ -1,4 +1,4 @@
-from idom import component, html, run
+from reactpy import component, html, run
@component
diff --git a/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_div.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_div.py
new file mode 100644
index 000000000..58ed79dd8
--- /dev/null
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_div.py
@@ -0,0 +1,13 @@
+from reactpy import component, html, run
+
+
+@component
+def MyTodoList():
+ return html.div(
+ html.h1("My Todo List"),
+ html.img({"src": "https://picsum.photos/id/0/500/300"}),
+ html.ul(html.li("The first thing I need to do is...")),
+ )
+
+
+run(MyTodoList)
diff --git a/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py
new file mode 100644
index 000000000..cc54d8b71
--- /dev/null
+++ b/docs/source/guides/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py
@@ -0,0 +1,13 @@
+from reactpy import component, html, run
+
+
+@component
+def MyTodoList():
+ return html._(
+ html.h1("My Todo List"),
+ html.img({"src": "https://picsum.photos/id/0/500/200"}),
+ html.ul(html.li("The first thing I need to do is...")),
+ )
+
+
+run(MyTodoList)
diff --git a/docs/source/creating-interfaces/your-first-components.rst b/docs/source/guides/creating-interfaces/your-first-components/index.rst
similarity index 55%
rename from docs/source/creating-interfaces/your-first-components.rst
rename to docs/source/guides/creating-interfaces/your-first-components/index.rst
index eeee7fa31..00b53d1b7 100644
--- a/docs/source/creating-interfaces/your-first-components.rst
+++ b/docs/source/guides/creating-interfaces/your-first-components/index.rst
@@ -1,10 +1,10 @@
Your First Components
=====================
-As we learned :ref:`earlier ` we can use IDOM to make rich structured
+As we learned :ref:`earlier ` we can use ReactPy to make rich structured
documents out of standard HTML elements. As these documents become larger and more
complex though, working with these tiny UI elements can become difficult. When this
-happens, IDOM allows you to group these elements together info "components". These
+happens, ReactPy allows you to group these elements together info "components". These
components can then be reused throughout your application.
@@ -16,9 +16,9 @@ component you just need to add a ``@component`` `decorator
`__ to a function. Functions
decorator in this way are known as **render function** and, by convention, we name them
like classes - with ``CamelCase``. So consider what we would do if we wanted to write,
-and then :ref:`display ` a ``Photo`` component:
+and then :ref:`display ` a ``Photo`` component:
-.. idom:: _examples/simple_photo
+.. reactpy:: _examples/simple_photo
.. warning::
@@ -39,7 +39,64 @@ can define a "parent" ``Gallery`` component that returns one or more ``Profile``
components. This is part of what makes components so powerful - you can define a
component once and use it wherever and however you need to:
-.. idom:: _examples/nested_photos
+.. reactpy:: _examples/nested_photos
+
+
+Return a Single Root Element
+----------------------------
+
+Components must return a "single root element". That one root element may have children,
+but you cannot for example, return a list of element from a component and expect it to
+be rendered correctly. If you want to return multiple elements you must wrap them in
+something like a :func:`html.div `:
+
+.. reactpy:: _examples/wrap_in_div
+
+If don't want to add an extra ``div`` you can use a "fragment" instead with the
+:func:`html._ ` function:
+
+.. reactpy:: _examples/wrap_in_fragment
+
+Fragments allow you to group elements together without leaving any trace in the UI. For
+example, the first code sample written with ReactPy will produce the second HTML code
+block:
+
+.. grid:: 1 2 2 2
+ :margin: 0
+ :padding: 0
+
+ .. grid-item::
+
+ .. testcode::
+
+ from reactpy import html
+
+ html.ul(
+ html._(
+ html.li("Group 1 Item 1"),
+ html.li("Group 1 Item 2"),
+ html.li("Group 1 Item 3"),
+ ),
+ html._(
+ html.li("Group 2 Item 1"),
+ html.li("Group 2 Item 2"),
+ html.li("Group 2 Item 3"),
+ )
+ )
+
+ .. grid-item::
+
+ .. code-block:: html
+
+
+
Group 1 Item 1
+
Group 1 Item 2
+
Group 1 Item 3
+
Group 2 Item 1
+
Group 2 Item 2
+
Group 2 Item 3
+
+
Parametrizing Components
@@ -50,7 +107,7 @@ parent components to pass information to child components. Where standard HTML e
are parametrized by dictionaries, since components behave like typical functions you can
give them positional and keyword arguments as you would normally:
-.. idom:: _examples/parametrized_photos
+.. reactpy:: _examples/parametrized_photos
Conditional Rendering
@@ -61,17 +118,17 @@ conditions. Let's imagine that we had a basic todo list where only some of the i
have been completed. Below we have a basic implementation for such a list except that
the ``Item`` component doesn't change based on whether it's ``done``:
-.. idom:: _examples/todo_list
+.. reactpy:: _examples/todo_list
Let's imagine that we want to add a â to the items which have been marked ``done=True``.
One way to do this might be to write an ``if`` statement where we return one ``li``
element if the item is ``done`` and a different one if it's not:
-.. idom:: _examples/bad_conditional_todo_list
+.. reactpy:: _examples/bad_conditional_todo_list
As you can see this accomplishes our goal! However, notice how similar ``html.li(name, "
â")`` and ``html.li(name)`` are. While in this case it isn't especially harmful, we
could make our code a little easier to read and maintain by using an "inline" ``if``
statement.
-.. idom:: _examples/good_conditional_todo_list
+.. reactpy:: _examples/good_conditional_todo_list
diff --git a/docs/source/guides/escape-hatches/_examples/material_ui_button_no_action.py b/docs/source/guides/escape-hatches/_examples/material_ui_button_no_action.py
new file mode 100644
index 000000000..3ad4dac5b
--- /dev/null
+++ b/docs/source/guides/escape-hatches/_examples/material_ui_button_no_action.py
@@ -0,0 +1,16 @@
+from reactpy import component, run, web
+
+mui = web.module_from_template(
+ "react@^17.0.0",
+ "@material-ui/core@4.12.4",
+ fallback="â",
+)
+Button = web.export(mui, "Button")
+
+
+@component
+def HelloWorld():
+ return Button({"color": "primary", "variant": "contained"}, "Hello World!")
+
+
+run(HelloWorld)
diff --git a/docs/source/guides/escape-hatches/_examples/material_ui_button_on_click.py b/docs/source/guides/escape-hatches/_examples/material_ui_button_on_click.py
new file mode 100644
index 000000000..3fc684005
--- /dev/null
+++ b/docs/source/guides/escape-hatches/_examples/material_ui_button_on_click.py
@@ -0,0 +1,30 @@
+import json
+
+import reactpy
+
+mui = reactpy.web.module_from_template(
+ "react@^17.0.0",
+ "@material-ui/core@4.12.4",
+ fallback="â",
+)
+Button = reactpy.web.export(mui, "Button")
+
+
+@reactpy.component
+def ViewButtonEvents():
+ event, set_event = reactpy.hooks.use_state(None)
+
+ return reactpy.html.div(
+ Button(
+ {
+ "color": "primary",
+ "variant": "contained",
+ "onClick": lambda event: set_event(event),
+ },
+ "Click Me!",
+ ),
+ reactpy.html.pre(json.dumps(event, indent=2)),
+ )
+
+
+reactpy.run(ViewButtonEvents)
diff --git a/docs/source/escape-hatches/_examples/super_simple_chart/app.py b/docs/source/guides/escape-hatches/_examples/super_simple_chart/main.py
similarity index 94%
rename from docs/source/escape-hatches/_examples/super_simple_chart/app.py
rename to docs/source/guides/escape-hatches/_examples/super_simple_chart/main.py
index 2f2e17556..4640785f8 100644
--- a/docs/source/escape-hatches/_examples/super_simple_chart/app.py
+++ b/docs/source/guides/escape-hatches/_examples/super_simple_chart/main.py
@@ -1,7 +1,6 @@
from pathlib import Path
-from idom import component, run, web
-
+from reactpy import component, run, web
file = Path(__file__).parent / "super-simple-chart.js"
ssc = web.module_from_file("super-simple-chart", file, fallback="â")
diff --git a/docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js b/docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js
similarity index 91%
rename from docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js
rename to docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js
index f14103d78..486e5c363 100644
--- a/docs/source/escape-hatches/_examples/super_simple_chart/super-simple-chart.js
+++ b/docs/source/guides/escape-hatches/_examples/super_simple_chart/super-simple-chart.js
@@ -8,7 +8,7 @@ export function bind(node, config) {
create: (component, props, children) => h(component, props, ...children),
render: (element) => render(element, node),
unmount: () => render(null, node),
- }
+ };
}
export function SuperSimpleChart(props) {
@@ -48,10 +48,9 @@ function makePath(props, domain, data, options) {
const getSvgX = (x) => ((x - xMin) / (xMax - xMin)) * width;
const getSvgY = (y) => height - ((y - yMin) / (yMax - yMin)) * height;
- let pathD = "M " + getSvgX(data[0].x) + " " + getSvgY(data[0].y) + " ";
- pathD += data.map((point, i) => {
- return "L " + getSvgX(point.x) + " " + getSvgY(point.y) + " ";
- });
+ let pathD =
+ `M ${getSvgX(data[0].x)} ${getSvgY(data[0].y)} ` +
+ data.map(({ x, y }, i) => `L ${getSvgX(x)} ${getSvgY(y)}`).join(" ");
return html`=40.8.0", "wheel"]
build-backend = "setuptools.build_meta"
-Then, we can creat the ``setup.py`` file which uses Setuptools. This will differ
+Then, we can create the ``setup.py`` file which uses Setuptools. This will differ
substantially from a normal ``setup.py`` file since, as part of the build process we'll
need to use NPM to bundle our Javascript. This requires customizing some of the build
commands in Setuptools like ``build``, ``sdist``, and ``develop``:
@@ -230,10 +230,10 @@ commands in Setuptools like ``build``, ``sdist``, and ``develop``:
name=PACKAGE_NAME,
version="0.0.1",
packages=find_packages(exclude=["tests*"]),
- classifiers=["Framework :: IDOM", ...],
- keywords=["IDOM", "components", ...],
- # install IDOM with this package
- install_requires=["idom"],
+ classifiers=["Framework :: ReactPy", ...],
+ keywords=["ReactPy", "components", ...],
+ # install ReactPy with this package
+ install_requires=["reactpy"],
# required in order to include static files like bundle.js using MANIFEST.in
include_package_data=True,
# we need access to the file system, so cannot be run from a zip file
@@ -297,7 +297,7 @@ up and running as quickly as possible.
.. _install NPM: https://www.npmjs.com/get-npm
.. _CDN: https://en.wikipedia.org/wiki/Content_delivery_network
.. _PyPI: https://pypi.org/
-.. _template repository: https://github.com/idom-team/idom-react-component-cookiecutter
+.. _template repository: https://github.com/reactive-python/reactpy-js-component-template
.. _web module: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
.. _Rollup: https://rollupjs.org/guide/en/
.. _Webpack: https://webpack.js.org/
diff --git a/docs/source/escape-hatches/index.rst b/docs/source/guides/escape-hatches/index.rst
similarity index 66%
rename from docs/source/escape-hatches/index.rst
rename to docs/source/guides/escape-hatches/index.rst
index ddf0be60e..3ef1b7122 100644
--- a/docs/source/escape-hatches/index.rst
+++ b/docs/source/guides/escape-hatches/index.rst
@@ -4,11 +4,10 @@ Escape Hatches
.. toctree::
:hidden:
- class-components
javascript-components
distributing-javascript
- writing-your-own-server
- writing-your-own-client
+ using-a-custom-backend
+ using-a-custom-client
.. note::
diff --git a/docs/source/escape-hatches/javascript-components.rst b/docs/source/guides/escape-hatches/javascript-components.rst
similarity index 87%
rename from docs/source/escape-hatches/javascript-components.rst
rename to docs/source/guides/escape-hatches/javascript-components.rst
index 4e0177dcf..f0a71b6b7 100644
--- a/docs/source/escape-hatches/javascript-components.rst
+++ b/docs/source/guides/escape-hatches/javascript-components.rst
@@ -3,12 +3,12 @@
Javascript Components
=====================
-While IDOM is a great tool for displaying HTML and responding to browser events with
+While ReactPy is a great tool for displaying HTML and responding to browser events with
pure Python, there are other projects which already allow you to do this inside
`Jupyter Notebooks `__
or in standard
`web apps `__.
-The real power of IDOM comes from its ability to seamlessly leverage the existing
+The real power of ReactPy comes from its ability to seamlessly leverage the existing
Javascript ecosystem. This can be accomplished in different ways for different reasons:
.. list-table::
@@ -18,7 +18,7 @@ Javascript ecosystem. This can be accomplished in different ways for different r
- Use Case
* - :ref:`Dynamically Loaded Components`
- - You want to **quickly experiment** with IDOM and the Javascript ecosystem.
+ - You want to **quickly experiment** with ReactPy and the Javascript ecosystem.
* - :ref:`Custom Javascript Components`
- You want to create polished software that can be **easily shared** with others.
@@ -35,18 +35,18 @@ Dynamically Loaded Components
Javascript` for more info. Instead, it's best used during exploratory phases of
development.
-IDOM makes it easy to draft your code when you're in the early stages of development by
+ReactPy makes it easy to draft your code when you're in the early stages of development by
using a CDN_ to dynamically load Javascript packages on the fly. In this example we'll
be using the ubiquitous React-based UI framework `Material UI`_.
-.. idom:: _examples/material_ui_button_no_action
+.. reactpy:: _examples/material_ui_button_no_action
So now that we can display a Material UI Button we probably want to make it do
something. Thankfully there's nothing new to learn here, you can pass event handlers to
the button just as you did when :ref:`getting started `. Thus, all
we need to do is add an ``onClick`` handler to the component:
-.. idom:: _examples/material_ui_button_on_click
+.. reactpy:: _examples/material_ui_button_on_click
.. _Custom Javascript Component:
@@ -55,7 +55,7 @@ Custom Javascript Components
----------------------------
For projects that will be shared with others, we recommend bundling your Javascript with
-Rollup_ or Webpack_ into a `web module`_. IDOM also provides a `template repository`_
+Rollup_ or Webpack_ into a `web module`_. ReactPy also provides a `template repository`_
that can be used as a blueprint to build a library of React components.
To work as intended, the Javascript bundle must export a function ``bind()`` that
@@ -132,7 +132,7 @@ Javascript that can run directly in the browser. This means we can't use fancy s
like `JSX `__ and instead will use
`htm `__ to simulate JSX in plain Javascript.
-.. idom:: _examples/super_simple_chart
+.. reactpy:: _examples/super_simple_chart
.. Links
@@ -140,7 +140,7 @@ like `JSX `__ and instead will us
.. _Material UI: https://material-ui.com/
.. _CDN: https://en.wikipedia.org/wiki/Content_delivery_network
-.. _template repository: https://github.com/idom-team/idom-react-component-cookiecutter
+.. _template repository: https://github.com/reactive-python/reactpy-js-component-template
.. _web module: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
.. _Rollup: https://rollupjs.org/guide/en/
.. _Webpack: https://webpack.js.org/
diff --git a/docs/source/guides/escape-hatches/using-a-custom-backend.rst b/docs/source/guides/escape-hatches/using-a-custom-backend.rst
new file mode 100644
index 000000000..f9d21208a
--- /dev/null
+++ b/docs/source/guides/escape-hatches/using-a-custom-backend.rst
@@ -0,0 +1,9 @@
+.. _Writing Your Own Backend:
+.. _Using a Custom Backend:
+
+Using a Custom Backend đ§
+=========================
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/guides/escape-hatches/using-a-custom-client.rst b/docs/source/guides/escape-hatches/using-a-custom-client.rst
new file mode 100644
index 000000000..95de23e59
--- /dev/null
+++ b/docs/source/guides/escape-hatches/using-a-custom-client.rst
@@ -0,0 +1,9 @@
+.. _Writing Your Own Client:
+.. _Using a Custom Client:
+
+Using a Custom Client đ§
+========================
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/guides/getting-started/_examples/debug_error_example.py b/docs/source/guides/getting-started/_examples/debug_error_example.py
new file mode 100644
index 000000000..dd0b212ab
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/debug_error_example.py
@@ -0,0 +1,20 @@
+from reactpy import component, html, run
+
+
+@component
+def App():
+ return html.div(GoodComponent(), BadComponent())
+
+
+@component
+def GoodComponent():
+ return html.p("This component rendered successfully")
+
+
+@component
+def BadComponent():
+ msg = "This component raised an error"
+ raise RuntimeError(msg)
+
+
+run(App)
diff --git a/docs/source/guides/getting-started/_examples/hello_world.py b/docs/source/guides/getting-started/_examples/hello_world.py
new file mode 100644
index 000000000..f38d9e38f
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/hello_world.py
@@ -0,0 +1,9 @@
+from reactpy import component, html, run
+
+
+@component
+def App():
+ return html.h1("Hello, world!")
+
+
+run(App)
diff --git a/docs/source/guides/getting-started/_examples/run_fastapi.py b/docs/source/guides/getting-started/_examples/run_fastapi.py
new file mode 100644
index 000000000..bb02e9d6a
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/run_fastapi.py
@@ -0,0 +1,22 @@
+# :lines: 11-
+
+from reactpy import run
+from reactpy.backend import fastapi as fastapi_server
+
+# the run() function is the entry point for examples
+fastapi_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from fastapi import FastAPI
+
+from reactpy import component, html
+from reactpy.backend.fastapi import configure
+
+
+@component
+def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+app = FastAPI()
+configure(app, HelloWorld)
diff --git a/docs/source/guides/getting-started/_examples/run_flask.py b/docs/source/guides/getting-started/_examples/run_flask.py
new file mode 100644
index 000000000..f98753784
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/run_flask.py
@@ -0,0 +1,22 @@
+# :lines: 11-
+
+from reactpy import run
+from reactpy.backend import flask as flask_server
+
+# the run() function is the entry point for examples
+flask_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from flask import Flask
+
+from reactpy import component, html
+from reactpy.backend.flask import configure
+
+
+@component
+def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+app = Flask(__name__)
+configure(app, HelloWorld)
diff --git a/docs/source/guides/getting-started/_examples/run_sanic.py b/docs/source/guides/getting-started/_examples/run_sanic.py
new file mode 100644
index 000000000..1dae9f6e0
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/run_sanic.py
@@ -0,0 +1,26 @@
+# :lines: 11-
+
+from reactpy import run
+from reactpy.backend import sanic as sanic_server
+
+# the run() function is the entry point for examples
+sanic_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from sanic import Sanic
+
+from reactpy import component, html
+from reactpy.backend.sanic import configure
+
+
+@component
+def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+app = Sanic("MyApp")
+configure(app, HelloWorld)
+
+
+if __name__ == "__main__":
+ app.run(port=8000)
diff --git a/docs/source/guides/getting-started/_examples/run_starlette.py b/docs/source/guides/getting-started/_examples/run_starlette.py
new file mode 100644
index 000000000..966b9ef77
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/run_starlette.py
@@ -0,0 +1,22 @@
+# :lines: 11-
+
+from reactpy import run
+from reactpy.backend import starlette as starlette_server
+
+# the run() function is the entry point for examples
+starlette_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from starlette.applications import Starlette
+
+from reactpy import component, html
+from reactpy.backend.starlette import configure
+
+
+@component
+def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+app = Starlette()
+configure(app, HelloWorld)
diff --git a/docs/source/guides/getting-started/_examples/run_tornado.py b/docs/source/guides/getting-started/_examples/run_tornado.py
new file mode 100644
index 000000000..b86126e63
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/run_tornado.py
@@ -0,0 +1,31 @@
+# :lines: 11-
+
+from reactpy import run
+from reactpy.backend import tornado as tornado_server
+
+# the run() function is the entry point for examples
+tornado_server.configure = lambda _, cmpt: run(cmpt)
+
+
+import tornado.ioloop
+import tornado.web
+
+from reactpy import component, html
+from reactpy.backend.tornado import configure
+
+
+@component
+def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+def make_app():
+ app = tornado.web.Application()
+ configure(app, HelloWorld)
+ return app
+
+
+if __name__ == "__main__":
+ app = make_app()
+ app.listen(8000)
+ tornado.ioloop.IOLoop.current().start()
diff --git a/docs/source/guides/getting-started/_examples/sample_app.py b/docs/source/guides/getting-started/_examples/sample_app.py
new file mode 100644
index 000000000..a1cc34e6d
--- /dev/null
+++ b/docs/source/guides/getting-started/_examples/sample_app.py
@@ -0,0 +1,3 @@
+import reactpy
+
+reactpy.run(reactpy.sample.SampleApp)
diff --git a/docs/source/guides/getting-started/_static/embed-doc-ex.html b/docs/source/guides/getting-started/_static/embed-doc-ex.html
new file mode 100644
index 000000000..589cb5d80
--- /dev/null
+++ b/docs/source/guides/getting-started/_static/embed-doc-ex.html
@@ -0,0 +1,8 @@
+
+
diff --git a/docs/source/guides/getting-started/_static/embed-reactpy-view/index.html b/docs/source/guides/getting-started/_static/embed-reactpy-view/index.html
new file mode 100644
index 000000000..146d715e4
--- /dev/null
+++ b/docs/source/guides/getting-started/_static/embed-reactpy-view/index.html
@@ -0,0 +1,31 @@
+
+
+
+
+ Example App
+
+
+
This is an Example App
+
Just below is an embedded ReactPy view...
+
+
+
+
diff --git a/docs/source/guides/getting-started/_static/embed-reactpy-view/main.py b/docs/source/guides/getting-started/_static/embed-reactpy-view/main.py
new file mode 100644
index 000000000..6e3687f27
--- /dev/null
+++ b/docs/source/guides/getting-started/_static/embed-reactpy-view/main.py
@@ -0,0 +1,22 @@
+from sanic import Sanic
+from sanic.response import file
+
+from reactpy import component, html
+from reactpy.backend.sanic import Options, configure
+
+app = Sanic("MyApp")
+
+
+@app.route("/")
+async def index(request):
+ return await file("index.html")
+
+
+@component
+def ReactPyView():
+ return html.code("This text came from an ReactPy App")
+
+
+configure(app, ReactPyView, Options(url_prefix="/_reactpy"))
+
+app.run(host="127.0.0.1", port=5000)
diff --git a/docs/source/getting-started/_static/embed-idom-view/screenshot.png b/docs/source/guides/getting-started/_static/embed-reactpy-view/screenshot.png
similarity index 100%
rename from docs/source/getting-started/_static/embed-idom-view/screenshot.png
rename to docs/source/guides/getting-started/_static/embed-reactpy-view/screenshot.png
diff --git a/docs/source/getting-started/_static/logo-django.svg b/docs/source/guides/getting-started/_static/logo-django.svg
similarity index 100%
rename from docs/source/getting-started/_static/logo-django.svg
rename to docs/source/guides/getting-started/_static/logo-django.svg
diff --git a/docs/source/getting-started/_static/logo-jupyter.svg b/docs/source/guides/getting-started/_static/logo-jupyter.svg
similarity index 100%
rename from docs/source/getting-started/_static/logo-jupyter.svg
rename to docs/source/guides/getting-started/_static/logo-jupyter.svg
diff --git a/docs/source/getting-started/_static/logo-plotly.svg b/docs/source/guides/getting-started/_static/logo-plotly.svg
similarity index 100%
rename from docs/source/getting-started/_static/logo-plotly.svg
rename to docs/source/guides/getting-started/_static/logo-plotly.svg
diff --git a/docs/source/getting-started/_static/idom-in-jupyterlab.gif b/docs/source/guides/getting-started/_static/reactpy-in-jupyterlab.gif
similarity index 100%
rename from docs/source/getting-started/_static/idom-in-jupyterlab.gif
rename to docs/source/guides/getting-started/_static/reactpy-in-jupyterlab.gif
diff --git a/docs/source/getting-started/_static/shared-client-state-server-slider.gif b/docs/source/guides/getting-started/_static/shared-client-state-server-slider.gif
similarity index 100%
rename from docs/source/getting-started/_static/shared-client-state-server-slider.gif
rename to docs/source/guides/getting-started/_static/shared-client-state-server-slider.gif
diff --git a/docs/source/guides/getting-started/index.rst b/docs/source/guides/getting-started/index.rst
new file mode 100644
index 000000000..dd210be60
--- /dev/null
+++ b/docs/source/guides/getting-started/index.rst
@@ -0,0 +1,123 @@
+Getting Started
+===============
+
+.. toctree::
+ :hidden:
+
+ installing-reactpy
+ running-reactpy
+
+.. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
+ :color: info
+ :animate: fade-in
+ :open:
+
+ .. grid:: 1 2 2 2
+
+ .. grid-item-card:: :octicon:`tools` Installing ReactPy
+ :link: installing-reactpy
+ :link-type: doc
+
+ Learn how ReactPy can be installed in a variety of different ways - with
+ different web servers and even in different frameworks.
+
+ .. grid-item-card:: :octicon:`play` Running ReactPy
+ :link: running-reactpy
+ :link-type: doc
+
+ See how ReactPy can be run with a variety of different production servers or be
+ added to existing applications.
+
+The fastest way to get started with ReactPy is to try it out in a `Juptyer Notebook
+`__.
+If you want to use a Notebook to work through the examples shown in this documentation,
+you'll need to replace calls to ``reactpy.run(App)`` with a line at the end of each cell
+that constructs the ``App()`` in question. If that doesn't make sense, the introductory
+notebook linked below will demonstrate how to do this:
+
+.. card::
+ :link: https://mybinder.org/v2/gh/reactive-python/reactpy-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb
+
+ .. image:: _static/reactpy-in-jupyterlab.gif
+ :scale: 72%
+ :align: center
+
+
+Section 1: Installing ReactPy
+-----------------------------
+
+The next fastest option is to install ReactPy along with a supported server (like
+``starlette``) with ``pip``:
+
+.. code-block:: bash
+
+ pip install "reactpy[starlette]"
+
+To check that everything is working you can run the sample application:
+
+.. code-block:: bash
+
+ python -c "import reactpy; reactpy.run(reactpy.sample.SampleApp)"
+
+.. note::
+
+ This launches a simple development server which is good enough for testing, but
+ probably not what you want to use in production. When deploying in production,
+ there's a number of different ways of :ref:`running ReactPy `.
+
+You should then see a few log messages:
+
+.. code-block:: text
+
+ 2022-03-27T11:58:59-0700 | WARNING | You are running a development server. Change this before deploying in production!
+ 2022-03-27T11:58:59-0700 | INFO | Running with 'Starlette' at http://127.0.0.1:8000
+
+The second log message includes a URL indicating where you should go to view the app.
+That will usually be http://127.0.0.1:8000. Once you go to that URL you should see
+something like this:
+
+.. card::
+
+ .. reactpy-view:: _examples/sample_app
+
+If you get a ``RuntimeError`` similar to the following:
+
+.. code-block:: text
+
+ Found none of the following builtin server implementations...
+
+Then be sure you run ``pip install "reactpy[starlette]"`` instead of just ``reactpy``. For
+anything else, report your issue in ReactPy's :discussion-type:`discussion forum
+`.
+
+.. card::
+ :link: installing-reactpy
+ :link-type: doc
+
+ :octicon:`book` Read More
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Learn how ReactPy can be installed in a variety of different ways - with different web
+ servers and even in different frameworks.
+
+
+Section 2: Running ReactPy
+--------------------------
+
+Once you've :ref:`installed ReactPy `, you'll want to learn how to run an
+application. Throughout most of the examples in this documentation, you'll see the
+:func:`~reactpy.backend.utils.run` function used. While it's convenient tool for
+development it shouldn't be used in production settings - it's slow, and could leak
+secrets through debug log messages.
+
+.. reactpy:: _examples/hello_world
+
+.. card::
+ :link: running-reactpy
+ :link-type: doc
+
+ :octicon:`book` Read More
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ See how ReactPy can be run with a variety of different production servers or be
+ added to existing applications.
diff --git a/docs/source/guides/getting-started/installing-reactpy.rst b/docs/source/guides/getting-started/installing-reactpy.rst
new file mode 100644
index 000000000..0b2ffc28a
--- /dev/null
+++ b/docs/source/guides/getting-started/installing-reactpy.rst
@@ -0,0 +1,121 @@
+Installing ReactPy
+==================
+
+You will typically ``pip`` install ReactPy to alongside one of it's natively supported
+backends. For example, if we want to run ReactPy using the `Starlette
+`__ backend you would run
+
+.. code-block:: bash
+
+ pip install "reactpy[starlette]"
+
+If you want to install a "pure" version of ReactPy **without a backend implementation**
+you can do so without any installation extras. You might do this if you wanted to
+:ref:`use a custom backend ` or if you wanted to manually pin
+the dependencies for your chosen backend:
+
+.. code-block:: bash
+
+ pip install reactpy
+
+
+Native Backends
+---------------
+
+ReactPy includes built-in support for a variety backend implementations. To install the
+required dependencies for each you should substitute ``starlette`` from the ``pip
+install`` command above with one of the options below:
+
+- ``fastapi`` - https://fastapi.tiangolo.com
+- ``flask`` - https://palletsprojects.com/p/flask/
+- ``sanic`` - https://sanicframework.org
+- ``starlette`` - https://www.starlette.io/
+- ``tornado`` - https://www.tornadoweb.org/en/stable/
+
+If you need to, you can install more than one option by separating them with commas:
+
+.. code-block:: bash
+
+ pip install "reactpy[fastapi,flask,sanic,starlette,tornado]"
+
+Once this is complete you should be able to :ref:`run ReactPy ` with your
+chosen implementation.
+
+
+Other Backends
+--------------
+
+While ReactPy can run in a variety of contexts, sometimes frameworks require extra work in
+order to integrate with them. In these cases, the ReactPy team distributes bindings for
+those frameworks as separate Python packages. For documentation on how to install and
+run ReactPy in these supported frameworks, follow the links below:
+
+.. raw:: html
+
+
+
+.. role:: transparent-text-color
+
+.. We add transparent-text-color to the text so it's not visible, but it's still
+.. searchable.
+
+.. grid:: 3
+
+ .. grid-item-card::
+ :link: https://github.com/reactive-python/reactpy-django
+ :img-background: _static/logo-django.svg
+ :class-card: card-logo-image
+
+ :transparent-text-color:`Django`
+
+ .. grid-item-card::
+ :link: https://github.com/reactive-python/reactpy-jupyter
+ :img-background: _static/logo-jupyter.svg
+ :class-card: card-logo-image
+
+ :transparent-text-color:`Jupyter`
+
+ .. grid-item-card::
+ :link: https://github.com/reactive-python/reactpy-dash
+ :img-background: _static/logo-plotly.svg
+ :class-card: card-logo-image
+
+ :transparent-text-color:`Plotly Dash`
+
+
+For Development
+---------------
+
+If you want to contribute to the development of ReactPy or modify it, you'll want to
+install a development version of ReactPy. This involves cloning the repository where ReactPy's
+source is maintained, and setting up a :ref:`development environment`. From there you'll
+be able to modifying ReactPy's source code and :ref:`run its tests ` to
+ensure the modifications you've made are backwards compatible. If you want to add a new
+feature to ReactPy you should write your own test that validates its behavior.
+
+If you have questions about how to modify ReactPy or help with its development, be sure to
+:discussion:`start a discussion `. The ReactPy team are always
+excited to :ref:`welcome ` new contributions and contributors
+of all kinds
+
+.. card::
+ :link: /about/contributor-guide
+ :link-type: doc
+
+ :octicon:`book` Read More
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Learn more about how to contribute to the development of ReactPy.
diff --git a/docs/source/guides/getting-started/running-reactpy.rst b/docs/source/guides/getting-started/running-reactpy.rst
new file mode 100644
index 000000000..8abbd574f
--- /dev/null
+++ b/docs/source/guides/getting-started/running-reactpy.rst
@@ -0,0 +1,221 @@
+Running ReactPy
+===============
+
+The simplest way to run ReactPy is with the :func:`~reactpy.backend.utils.run` function. This
+is the method you'll see used throughout this documentation. However, this executes your
+application using a development server which is great for testing, but probably not what
+if you're :ref:`deploying in production `. Below are some
+more robust and performant ways of running ReactPy with various supported servers.
+
+
+Running ReactPy in Production
+-----------------------------
+
+The first thing you'll need to do if you want to run ReactPy in production is choose a
+backend implementation and follow its documentation on how to create and run an
+application. This is the backend :ref:`you probably chose ` when
+installing ReactPy. Then you'll need to configure that application with an ReactPy view. We
+show the basics of how to set up, and then run, each supported backend below, but all
+implementations will follow a pattern similar to the following:
+
+.. code-block::
+
+ from my_chosen_backend import Application
+
+ from reactpy import component, html
+ from reactpy.backend.my_chosen_backend import configure
+
+
+ @component
+ def HelloWorld():
+ return html.h1("Hello, world!")
+
+
+ app = Application()
+ configure(app, HelloWorld)
+
+You'll then run this ``app`` using an `ASGI `__
+or `WSGI `__ server from the command line.
+
+
+Running with `FastAPI `__
+.......................................................
+
+.. reactpy:: _examples/run_fastapi
+
+Then assuming you put this in ``main.py``, you can run the ``app`` using the `Uvicorn
+`__ ASGI server:
+
+.. code-block:: bash
+
+ uvicorn main:app
+
+
+Running with `Flask `__
+.............................................................
+
+.. reactpy:: _examples/run_flask
+
+Then assuming you put this in ``main.py``, you can run the ``app`` using the `Gunicorn
+`__ WSGI server:
+
+.. code-block:: bash
+
+ gunicorn main:app
+
+
+Running with `Sanic `__
+...................................................
+
+.. reactpy:: _examples/run_sanic
+
+Then assuming you put this in ``main.py``, you can run the ``app`` using Sanic's builtin
+server:
+
+.. code-block:: bash
+
+ sanic main.app
+
+
+Running with `Starlette `__
+......................................................
+
+.. reactpy:: _examples/run_starlette
+
+Then assuming you put this in ``main.py``, you can run the application using the
+`Uvicorn `__ ASGI server:
+
+.. code-block:: bash
+
+ uvicorn main:app
+
+
+Running with `Tornado `__
+................................................................
+
+.. reactpy:: _examples/run_tornado
+
+Tornado is run using it's own builtin server rather than an external WSGI or ASGI
+server.
+
+
+Running ReactPy in Debug Mode
+-----------------------------
+
+ReactPy provides a debug mode that is turned off by default. This can be enabled when you
+run your application by setting the ``REACTPY_DEBUG_MODE`` environment variable.
+
+.. tab-set::
+
+ .. tab-item:: Unix Shell
+
+ .. code-block::
+
+ export REACTPY_DEBUG_MODE=1
+ python my_reactpy_app.py
+
+ .. tab-item:: Command Prompt
+
+ .. code-block:: text
+
+ set REACTPY_DEBUG_MODE=1
+ python my_reactpy_app.py
+
+ .. tab-item:: PowerShell
+
+ .. code-block:: powershell
+
+ $env:REACTPY_DEBUG_MODE = "1"
+ python my_reactpy_app.py
+
+.. danger::
+
+ Leave debug mode off in production!
+
+Among other things, running in this mode:
+
+- Turns on debug log messages
+- Adds checks to ensure the :ref:`VDOM` spec is adhered to
+- Displays error messages that occur within your app
+
+Errors will be displayed where the uppermost component is located in the view:
+
+.. reactpy:: _examples/debug_error_example
+
+
+Backend Configuration Options
+-----------------------------
+
+ReactPy's various backend implementations come with ``Options`` that can be passed to their
+respective ``configure()`` functions in the following way:
+
+.. code-block::
+
+ from reactpy.backend. import configure, Options
+
+ configure(app, MyComponent, Options(...))
+
+To learn more read about the options for your chosen backend ````:
+
+- :class:`reactpy.backend.fastapi.Options`
+- :class:`reactpy.backend.flask.Options`
+- :class:`reactpy.backend.sanic.Options`
+- :class:`reactpy.backend.starlette.Options`
+- :class:`reactpy.backend.tornado.Options`
+
+
+Embed in an Existing Webpage
+----------------------------
+
+ReactPy provides a Javascript client called ``@reactpy/client`` that can be used to embed
+ReactPy views within an existing applications. This is actually how the interactive
+examples throughout this documentation have been created. You can try this out by
+embedding one the examples from this documentation into your own webpage:
+
+.. tab-set::
+
+ .. tab-item:: HTML
+
+ .. literalinclude:: _static/embed-doc-ex.html
+ :language: html
+
+ .. tab-item:: âļī¸ Result
+
+ .. raw:: html
+ :file: _static/embed-doc-ex.html
+
+.. note::
+
+ For more information on how to use the client see the :ref:`Javascript API`
+ reference. Or if you need to, your can :ref:`write your own backend implementation
+ `.
+
+As mentioned though, this is connecting to the server that is hosting this
+documentation. If you want to connect to a view from your own server, you'll need to
+change the URL above to one you provide. One way to do this might be to add to an
+existing application. Another would be to run ReactPy in an adjacent web server instance
+that you coordinate with something like `NGINX `__. For the sake
+of simplicity, we'll assume you do something similar to the following in an existing
+Python app:
+
+.. tab-set::
+
+ .. tab-item:: main.py
+
+ .. literalinclude:: _static/embed-reactpy-view/main.py
+ :language: python
+
+ .. tab-item:: index.html
+
+ .. literalinclude:: _static/embed-reactpy-view/index.html
+ :language: html
+
+After running ``python main.py``, you should be able to navigate to
+``http://127.0.0.1:8000/index.html`` and see:
+
+.. card::
+ :text-align: center
+
+ .. image:: _static/embed-reactpy-view/screenshot.png
+ :width: 500px
+
diff --git a/docs/source/guides/managing-state/combining-contexts-and-reducers/index.rst b/docs/source/guides/managing-state/combining-contexts-and-reducers/index.rst
new file mode 100644
index 000000000..b9f274f0a
--- /dev/null
+++ b/docs/source/guides/managing-state/combining-contexts-and-reducers/index.rst
@@ -0,0 +1,6 @@
+Combining Contexts and Reducers đ§
+==================================
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/guides/managing-state/deeply-sharing-state-with-contexts/index.rst b/docs/source/guides/managing-state/deeply-sharing-state-with-contexts/index.rst
new file mode 100644
index 000000000..4a00caa48
--- /dev/null
+++ b/docs/source/guides/managing-state/deeply-sharing-state-with-contexts/index.rst
@@ -0,0 +1,6 @@
+Deeply Sharing State with Contexts đ§
+=====================================
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/managing-state/structuring-your-state.rst b/docs/source/guides/managing-state/how-to-structure-state/index.rst
similarity index 77%
rename from docs/source/managing-state/structuring-your-state.rst
rename to docs/source/guides/managing-state/how-to-structure-state/index.rst
index 68209cccf..5092370a5 100644
--- a/docs/source/managing-state/structuring-your-state.rst
+++ b/docs/source/guides/managing-state/how-to-structure-state/index.rst
@@ -1,6 +1,6 @@
.. _Structuring Your State:
-Structuring Your State đ§
+How to Structure State đ§
=========================
.. note::
diff --git a/docs/source/guides/managing-state/index.rst b/docs/source/guides/managing-state/index.rst
new file mode 100644
index 000000000..0578bafdd
--- /dev/null
+++ b/docs/source/guides/managing-state/index.rst
@@ -0,0 +1,127 @@
+Managing State
+==============
+
+.. toctree::
+ :hidden:
+
+ how-to-structure-state/index
+ sharing-component-state/index
+ when-and-how-to-reset-state/index
+ simplifying-updates-with-reducers/index
+ deeply-sharing-state-with-contexts/index
+ combining-contexts-and-reducers/index
+
+.. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
+ :color: info
+ :animate: fade-in
+ :open:
+
+ .. grid:: 1 2 2 2
+
+ .. grid-item-card:: :octicon:`organization` How to Structure State
+ :link: how-to-structure-state/index
+ :link-type: doc
+
+ Make it easy to reason about your application with strategies for organizing
+ state.
+
+ .. grid-item-card:: :octicon:`link` Sharing Component State
+ :link: sharing-component-state/index
+ :link-type: doc
+
+ Allow components to vary vary together, by lifting state into common
+ parents.
+
+ .. grid-item-card:: :octicon:`light-bulb` When and How to Reset State
+ :link: when-and-how-to-reset-state/index
+ :link-type: doc
+
+ Control if and how state is preserved by understanding it's relationship to
+ the "UI tree".
+
+ .. grid-item-card:: :octicon:`plug` Simplifying Updates with Reducers
+ :link: simplifying-updates-with-reducers/index
+ :link-type: doc
+
+ Consolidate state update logic outside your component in a single function,
+ called a âreducer".
+
+ .. grid-item-card:: :octicon:`broadcast` Deeply Sharing State with Contexts
+ :link: deeply-sharing-state-with-contexts/index
+ :link-type: doc
+
+ Instead of passing shared state down deep component trees, bring state into
+ "contexts" instead.
+
+ .. grid-item-card:: :octicon:`rocket` Combining Contexts and Reducers
+ :link: combining-contexts-and-reducers/index
+ :link-type: doc
+
+ You can combine reducers and context together to manage state of a complex
+ screen.
+
+
+Section 1: How to Structure State
+---------------------------------
+
+.. note::
+
+ Under construction đ§
+
+
+Section 2: Shared Component State
+---------------------------------
+
+Sometimes, you want the state of two components to always change together. To do it,
+remove state from both of them, move it to their closest common parent, and then pass it
+down to them via props. This is known as âlifting state upâ, and itâs one of the most
+common things you will do writing code with ReactPy.
+
+In the example below the search input and the list of elements below share the same
+state, the state represents the food name. Note how the component ``Table`` gets called
+at each change of state. The component is observing the state and reacting to state
+changes automatically, just like it would do in React.
+
+.. reactpy:: sharing-component-state/_examples/synced_inputs
+
+.. card::
+ :link: sharing-component-state/index
+ :link-type: doc
+
+ :octicon:`book` Read More
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ Allow components to vary vary together, by lifting state into common parents.
+
+
+Section 3: When and How to Reset State
+--------------------------------------
+
+.. note::
+
+ Under construction đ§
+
+
+Section 4: Simplifying Updates with Reducers
+--------------------------------------------
+
+.. note::
+
+ Under construction đ§
+
+
+Section 5: Deeply Sharing State with Contexts
+---------------------------------------------
+
+.. note::
+
+ Under construction đ§
+
+
+
+Section 6: Combining Contexts and Reducers
+------------------------------------------
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/data.json b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/data.json
new file mode 100644
index 000000000..f977fe9a7
--- /dev/null
+++ b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/data.json
@@ -0,0 +1,22 @@
+[
+ {
+ "name": "Sushi",
+ "description": "Sushi is a traditional Japanese dish of prepared vinegared rice"
+ },
+ {
+ "name": "Dal",
+ "description": "The most common way of preparing dal is in the form of a soup to which onions, tomatoes and various spices may be added"
+ },
+ {
+ "name": "Pierogi",
+ "description": "Pierogi are filled dumplings made by wrapping unleavened dough around a savoury or sweet filling and cooking in boiling water"
+ },
+ {
+ "name": "Shish Kebab",
+ "description": "Shish kebab is a popular meal of skewered and grilled cubes of meat"
+ },
+ {
+ "name": "Dim sum",
+ "description": "Dim sum is a large range of small dishes that Cantonese people traditionally enjoy in restaurants for breakfast and lunch"
+ }
+]
diff --git a/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/main.py b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/main.py
new file mode 100644
index 000000000..ca68aedcb
--- /dev/null
+++ b/docs/source/guides/managing-state/sharing-component-state/_examples/filterable_list/main.py
@@ -0,0 +1,44 @@
+import json
+from pathlib import Path
+
+from reactpy import component, hooks, html, run
+
+HERE = Path(__file__)
+DATA_PATH = HERE.parent / "data.json"
+food_data = json.loads(DATA_PATH.read_text())
+
+
+@component
+def FilterableList():
+ value, set_value = hooks.use_state("")
+ return html.p(Search(value, set_value), html.hr(), Table(value, set_value))
+
+
+@component
+def Search(value, set_value):
+ def handle_change(event):
+ set_value(event["target"]["value"])
+
+ return html.label(
+ "Search by Food Name: ",
+ html.input({"value": value, "on_change": handle_change}),
+ )
+
+
+@component
+def Table(value, set_value):
+ rows = []
+ for row in food_data:
+ name = html.td(row["name"])
+ descr = html.td(row["description"])
+ tr = html.tr(name, descr, value)
+ if not value:
+ rows.append(tr)
+ elif value.lower() in row["name"].lower():
+ rows.append(tr)
+ headers = html.tr(html.td(html.b("name")), html.td(html.b("description")))
+ table = html.table(html.thead(headers), html.tbody(rows))
+ return table
+
+
+run(FilterableList)
diff --git a/docs/source/guides/managing-state/sharing-component-state/_examples/synced_inputs/main.py b/docs/source/guides/managing-state/sharing-component-state/_examples/synced_inputs/main.py
new file mode 100644
index 000000000..e8bcdf333
--- /dev/null
+++ b/docs/source/guides/managing-state/sharing-component-state/_examples/synced_inputs/main.py
@@ -0,0 +1,23 @@
+from reactpy import component, hooks, html, run
+
+
+@component
+def SyncedInputs():
+ value, set_value = hooks.use_state("")
+ return html.p(
+ Input("First input", value, set_value),
+ Input("Second input", value, set_value),
+ )
+
+
+@component
+def Input(label, value, set_value):
+ def handle_change(event):
+ set_value(event["target"]["value"])
+
+ return html.label(
+ label + " ", html.input({"value": value, "on_change": handle_change})
+ )
+
+
+run(SyncedInputs)
diff --git a/docs/source/guides/managing-state/sharing-component-state/index.rst b/docs/source/guides/managing-state/sharing-component-state/index.rst
new file mode 100644
index 000000000..54b61335a
--- /dev/null
+++ b/docs/source/guides/managing-state/sharing-component-state/index.rst
@@ -0,0 +1,38 @@
+Sharing Component State
+=======================
+
+.. note::
+
+ Parts of this document are still under construction đ§
+
+Sometimes, you want the state of two components to always change together. To do it,
+remove state from both of them, move it to their closest common parent, and then pass it
+down to them via props. This is known as âlifting state upâ, and itâs one of the most
+common things you will do writing code with ReactPy.
+
+
+Synced Inputs
+-------------
+
+In the code below the two input boxes are synchronized, this happens because they share
+state. The state is shared via the parent component ``SyncedInputs``. Check the ``value``
+and ``set_value`` variables.
+
+.. reactpy:: _examples/synced_inputs
+
+
+Filterable List
+----------------
+
+In the example below the search input and the list of elements below share the
+same state, the state represents the food name.
+
+Note how the component ``Table`` gets called at each change of state. The
+component is observing the state and reacting to state changes automatically,
+just like it would do in React.
+
+.. reactpy:: _examples/filterable_list
+
+.. note::
+
+ Try typing a food name in the search bar.
diff --git a/docs/source/guides/managing-state/simplifying-updates-with-reducers/index.rst b/docs/source/guides/managing-state/simplifying-updates-with-reducers/index.rst
new file mode 100644
index 000000000..08fce5a69
--- /dev/null
+++ b/docs/source/guides/managing-state/simplifying-updates-with-reducers/index.rst
@@ -0,0 +1,6 @@
+Simplifying Updates with Reducers đ§
+====================================
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/managing-state/when-to-reset-state.rst b/docs/source/guides/managing-state/when-and-how-to-reset-state/index.rst
similarity index 50%
rename from docs/source/managing-state/when-to-reset-state.rst
rename to docs/source/guides/managing-state/when-and-how-to-reset-state/index.rst
index 2a0b8c3ae..6a96f4b30 100644
--- a/docs/source/managing-state/when-to-reset-state.rst
+++ b/docs/source/guides/managing-state/when-and-how-to-reset-state/index.rst
@@ -1,7 +1,7 @@
.. _When to Reset State:
-When to Reset State đ§
-======================
+When and How to Reset State đ§
+==============================
.. note::
diff --git a/docs/source/understanding-idom/_static/idom-flow-diagram.svg b/docs/source/guides/understanding-reactpy/_static/idom-flow-diagram.svg
similarity index 99%
rename from docs/source/understanding-idom/_static/idom-flow-diagram.svg
rename to docs/source/guides/understanding-reactpy/_static/idom-flow-diagram.svg
index 27c78b0b2..9077913ca 100644
--- a/docs/source/understanding-idom/_static/idom-flow-diagram.svg
+++ b/docs/source/guides/understanding-reactpy/_static/idom-flow-diagram.svg
@@ -13,7 +13,7 @@
viewBox="-0.5 -0.5 680 580"
content="<mxfile host="app.diagrams.net" modified="2020-09-07T18:34:20.858Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.83 Safari/537.36" etag="IvUE9xI9CxZQnD7O0sJm" version="13.6.6" type="device"><diagram id="3GUrj3vU2Wc3lj3yRkW7" name="Page-1">7Zpdb9owFIZ/DZetkrgEuCy027R1XSWkddqdiU8Sqw5mjvnar5+d2CEhFEpbPkZBlUqO7WP7+D0PdpIG6iWzzwKP4u+cAGt4Dpk10E3D89wrz2voP4fMc0sLdXJDJCgxlRaGPv0Lxtg01jElkFYqSs6ZpKOqMeDDIQSyYsNC8Gm1WshZtdcRjqBm6AeY1a2PlMg4t7abzsL+BWgU255dx5Qk2FY2hjTGhE9LJnTbQD3Bucy/JbMeMB08G5e83adnSouBCRjKlzTAv+WFQ760viXebfT49/4J/cIXfu5lgtnYTLjh+Uz564ZcuVUBw0Fe4P8Z65F2e3wsKAhVdA/ThVlPUM5Zta72cZFma3qtKqjRzsot/Mj8zzocWMMdnvOxtGY1ocFyVWXLh2fNXqV7T/DxkICet6uKpzGV0B/lE5kqmSpbLBNmikPKWI8zLrK2iGBoh4Gyp1LwJyiV+EEbBmFRYuWAihFMQEiYPbs8brHoKluAJyDFXFUxDTzX6MQkim8upwvVFckUlxRn62Ej9KjwvNCC+mLksIU0WkcojRuajrAMYt3Jx5ZHcX0wfbSPUB+PoL46fRCTs0LQwQnSOUKF9BiF4dofl4H4iGppHpwn7iqgLEUahuRab+rUVcBwmtKgGtxqqJr1cINLmtBaFe6O30LYL4ILpLYv3BjaUujs/rAcOWsTwLCkk6r7VeE0PTxwmmXLbGml5naVllYkVUkUgGlV3hBucFRcW0cSiwhkzVG2usW037DgG/mwddJvQZQ8l7/2f9yrsge9qXhpumtp3OGBOuhUtIcZjYZamEomqkPU1flJ1Uni2hQklBDtoytAzQAPMn+Ouh7pCGcxb3YbzRtlYdp9FwdPUcaWkkw/ZZ91DDAnIeN/cf4oC3hNAj5LDOfSayNUUYz7NkEbLxduq9qEh2EKO5GcHdyZMdsxxmu9E2PQ8s/Hjhlj1/fMmNcwRg/R3JLxnJ0wZ8MuZYfMQXtjDjoz5zXMcd9rX+PteV/jXR2eOT9vfnw/s2ZVIp42a1Ztqd+bNWEIfrDyyEpanYHj/AesQWgDIl7KmmVHNWjtmDW2+8Pub1TJ7aR6W+VMnCId90+c/QEH7eNAdYLAqZ2DXguc2sls18A5igPVGTjr0vGkgbOP09QJAqd2c/e1wKndbt41cI7gNHUGzvp0PGXgXG3cYW+rpkcYpDx4gkJM2z9xzNb+gadUUq5lI3J+FPpiEMqVoEtjPNI+klmk39e6TNRAxqPLBAv9LxgLNu+KbD4VYNpXl7SICE7j7GGns/J2U/bR1ahQisqHp1ijR/Cukn35o07fvku2TLANJO5s/6RTXS5e6MoVuHgtDt3+Aw==</diagram></mxfile>"
id="svg4818"
- sodipodi:docname="idom-flow-diagram.svg"
+ sodipodi:docname="reactpy-flow-diagram.svg"
inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)">
diff --git a/docs/source/understanding-idom/_static/live-examples-in-docs.gif b/docs/source/guides/understanding-reactpy/_static/live-examples-in-docs.gif
similarity index 100%
rename from docs/source/understanding-idom/_static/live-examples-in-docs.gif
rename to docs/source/guides/understanding-reactpy/_static/live-examples-in-docs.gif
diff --git a/docs/source/understanding-idom/_static/mvc-flow-diagram.svg b/docs/source/guides/understanding-reactpy/_static/mvc-flow-diagram.svg
similarity index 100%
rename from docs/source/understanding-idom/_static/mvc-flow-diagram.svg
rename to docs/source/guides/understanding-reactpy/_static/mvc-flow-diagram.svg
diff --git a/docs/source/understanding-idom/_static/npm-download-trends.png b/docs/source/guides/understanding-reactpy/_static/npm-download-trends.png
similarity index 100%
rename from docs/source/understanding-idom/_static/npm-download-trends.png
rename to docs/source/guides/understanding-reactpy/_static/npm-download-trends.png
diff --git a/docs/source/understanding-idom/index.rst b/docs/source/guides/understanding-reactpy/index.rst
similarity index 54%
rename from docs/source/understanding-idom/index.rst
rename to docs/source/guides/understanding-reactpy/index.rst
index 5c1b94231..3e0b2ab72 100644
--- a/docs/source/understanding-idom/index.rst
+++ b/docs/source/guides/understanding-reactpy/index.rst
@@ -1,5 +1,5 @@
-Understanding IDOM
-==================
+Understanding ReactPy
+=====================
.. toctree::
:hidden:
@@ -7,6 +7,11 @@ Understanding IDOM
representing-html
what-are-components
the-rendering-pipeline
- why-idom-needs-keys
+ why-reactpy-needs-keys
the-rendering-process
layout-render-servers
+ writing-tests
+
+.. note::
+
+ Under construction đ§
diff --git a/docs/source/understanding-idom/layout-render-servers.rst b/docs/source/guides/understanding-reactpy/layout-render-servers.rst
similarity index 100%
rename from docs/source/understanding-idom/layout-render-servers.rst
rename to docs/source/guides/understanding-reactpy/layout-render-servers.rst
diff --git a/docs/source/understanding-idom/representing-html.rst b/docs/source/guides/understanding-reactpy/representing-html.rst
similarity index 89%
rename from docs/source/understanding-idom/representing-html.rst
rename to docs/source/guides/understanding-reactpy/representing-html.rst
index ffae0d331..c2f32ebd9 100644
--- a/docs/source/understanding-idom/representing-html.rst
+++ b/docs/source/guides/understanding-reactpy/representing-html.rst
@@ -7,10 +7,10 @@ Representing HTML đ§
Under construction đ§
-We've already discussed how to contruct HTML with IDOM in a :ref:`previous section `, but we skimmed over the question of the data structure we use to represent
+We've already discussed how to construct HTML with ReactPy in a :ref:`previous section `, but we skimmed over the question of the data structure we use to represent
it. Let's reconsider the examples from before - on the top is some HTML and on the
-bottom is the corresponding code to create it in IDOM:
+bottom is the corresponding code to create it in ReactPy:
.. code-block:: html
@@ -24,7 +24,7 @@ bottom is the corresponding code to create it in IDOM:
.. testcode::
- from idom import html
+ from reactpy import html
layout = html.div(
html.h1("My Todo List"),
diff --git a/docs/source/understanding-idom/the-rendering-pipeline.rst b/docs/source/guides/understanding-reactpy/the-rendering-pipeline.rst
similarity index 100%
rename from docs/source/understanding-idom/the-rendering-pipeline.rst
rename to docs/source/guides/understanding-reactpy/the-rendering-pipeline.rst
diff --git a/docs/source/understanding-idom/the-rendering-process.rst b/docs/source/guides/understanding-reactpy/the-rendering-process.rst
similarity index 100%
rename from docs/source/understanding-idom/the-rendering-process.rst
rename to docs/source/guides/understanding-reactpy/the-rendering-process.rst
diff --git a/docs/source/understanding-idom/what-are-components.rst b/docs/source/guides/understanding-reactpy/what-are-components.rst
similarity index 100%
rename from docs/source/understanding-idom/what-are-components.rst
rename to docs/source/guides/understanding-reactpy/what-are-components.rst
diff --git a/docs/source/managing-state/shared-component-state.rst b/docs/source/guides/understanding-reactpy/why-reactpy-needs-keys.rst
similarity index 54%
rename from docs/source/managing-state/shared-component-state.rst
rename to docs/source/guides/understanding-reactpy/why-reactpy-needs-keys.rst
index 3c9f66617..e570b8f41 100644
--- a/docs/source/managing-state/shared-component-state.rst
+++ b/docs/source/guides/understanding-reactpy/why-reactpy-needs-keys.rst
@@ -1,6 +1,6 @@
-.. _Shared Component State:
+.. _Why ReactPy Needs Keys:
-Shared Component State đ§
+Why ReactPy Needs Keys đ§
=========================
.. note::
diff --git a/docs/source/managing-state/writing-tests.rst b/docs/source/guides/understanding-reactpy/writing-tests.rst
similarity index 100%
rename from docs/source/managing-state/writing-tests.rst
rename to docs/source/guides/understanding-reactpy/writing-tests.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e7ecbc18d..8b21160f6 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,80 +1,81 @@
.. card::
This documentation is still under construction đ§. We welcome your `feedback
- `__!
+ `__!
-What is IDOM?
-=============
+ReactPy
+=======
.. toctree::
:hidden:
- :caption: User Guide
+ :caption: Guides
- getting-started/index
- creating-interfaces/index
- adding-interactivity/index
- managing-state/index
- escape-hatches/index
- understanding-idom/index
+ guides/getting-started/index
+ guides/creating-interfaces/index
+ guides/adding-interactivity/index
+ guides/managing-state/index
+ guides/escape-hatches/index
+ guides/understanding-reactpy/index
.. toctree::
:hidden:
- :caption: Other Resources
+ :caption: Reference
- developing-idom/index
- reference-material/index
- credits-and-licenses
+ reference/browser-events
+ reference/html-attributes
+ reference/hooks-api
+ _auto/apis
+ reference/javascript-api
+ reference/specifications
.. toctree::
:hidden:
- :caption: External Links
+ :caption: About
- Source Code
- Community
- Issues
+ about/changelog
+ about/contributor-guide
+ about/credits-and-licenses
+ Source Code
+ Community
-
-IDOM is a Python web framework for building **interactive websites without needing a
-single line of Javascript**. This is accomplished by breaking down complex applications
-into nestable and reusable chunks of code called :ref:`"components" ` that allow you to focus on what your application does rather than how it
-does it.
-
-Ecosystem independence is also a core feature of IDOM. It can be added to existing
-applications built on a variety of sync and async web servers, as well as integrated
-with other frameworks like Django, Jupyter, and Plotly Dash. Not only does this mean
-you're free to choose what technology stack to run on, but on top of that, you can run
-the exact same components wherever you need them. For example, you can take a component
-originally developed in a Jupyter Notebook and embed it in your production application
-without changing anything about the component itself.
+ReactPy is a library for building user interfaces in Python without Javascript. ReactPy
+interfaces are made from :ref:`components ` which look and behave
+similarly to those found in `ReactJS `__. Designed with simplicity
+in mind, ReactPy can be used by those without web development experience while also
+being powerful enough to grow with your ambitions.
At a Glance
-----------
-To get a rough idea of how to write apps in IDOM, take a look at the tiny `"hello world"
+To get a rough idea of how to write apps in ReactPy, take a look at the tiny `"hello world"
`__ application below:
-.. idom:: getting-started/_examples/hello_world
+.. reactpy:: guides/getting-started/_examples/hello_world
.. hint::
- Try clicking the **âļī¸ result** tab to see what this displays!
+ Try clicking the **đ result** tab to see what this displays!
-So what exactly does this code do? First, it imports a few tools from ``idom`` that will
+So what exactly does this code do? First, it imports a few tools from ``reactpy`` that will
get used to describe and execute an application. Then, we create an ``App`` function
which will define the content the application displays. Specifically, it displays a kind
of HTML element called an ``h1`` `section heading
`__.
Importantly though, a ``@component`` decorator has been applied to the ``App`` function
to turn it into a :ref:`component `. Finally, we :ref:`run
-` an application server by passing the ``App`` component to the ``run()``
-function.
+` a development web server by passing the ``App`` component to the
+``run()`` function.
+
+.. note::
+
+ See :ref:`Running ReactPy in Production` to learn how to use a production-grade server
+ to run ReactPy.
-Learning IDOM
--------------
+Learning ReactPy
+----------------
This documentation is broken up into chapters and sections that introduce you to
concepts step by step with detailed explanations and lots of examples. You should feel
@@ -88,45 +89,45 @@ Chapter 1 - :ref:`Getting Started`
-----------------------------------
If you want to follow along with examples in the sections that follow, you'll want to
-start here so you can :ref:`install IDOM `. This section also contains
-more detailed information about how to :ref:`run IDOM ` in different
-contexts. For example, if you want to embed IDOM into an existing application, or run
-IDOM within a Jupyter Notebook, this is where you can learn how to do those things.
+start here so you can :ref:`install ReactPy `. This section also contains
+more detailed information about how to :ref:`run ReactPy ` in different
+contexts. For example, if you want to embed ReactPy into an existing application, or run
+ReactPy within a Jupyter Notebook, this is where you can learn how to do those things.
.. grid:: 1 2 2 2
.. grid-item::
- .. image:: _static/install-and-run-idom.gif
+ .. image:: _static/install-and-run-reactpy.gif
.. grid-item::
- .. image:: getting-started/_static/idom-in-jupyterlab.gif
+ .. image:: guides/getting-started/_static/reactpy-in-jupyterlab.gif
.. card::
- :link: getting-started/index
+ :link: guides/getting-started/index
:link-type: doc
:octicon:`book` Read More
^^^^^^^^^^^^^^^^^^^^^^^^^
- Install IDOM and run it in a variety of different ways - with different web servers
- and frameworks. You'll even embed IDOM into an existing app.
+ Install ReactPy and run it in a variety of different ways - with different web servers
+ and frameworks. You'll even embed ReactPy into an existing app.
Chapter 2 - :ref:`Creating Interfaces`
--------------------------------------
-IDOM is a Python package for making user interfaces (UI). These interfaces are built
-from small elements of functionality like buttons text and images. IDOM allows you to
+ReactPy is a Python package for making user interfaces (UI). These interfaces are built
+from small elements of functionality like buttons text and images. ReactPy allows you to
combine these elements into reusable :ref:`"components" `. In the
sections that follow you'll learn how these UI elements are created and organized into
components. Then, you'll use this knowledge to create interfaces from raw data:
-.. idom:: creating-interfaces/_examples/todo_list_with_keys
+.. reactpy:: guides/creating-interfaces/rendering-data/_examples/todo_list_with_keys
.. card::
- :link: creating-interfaces/index
+ :link: guides/creating-interfaces/index
:link-type: doc
:octicon:`book` Read More
@@ -142,20 +143,20 @@ Components often need to change whatâs on the screen as a result of an interac
example, typing into the form should update the input field, clicking a âCommentâ button
should bring up a text input field, clicking âBuyâ should put a product in the shopping
cart. Components need to ârememberâ things like the current input value, the current
-image, the shopping cart. In IDOM, this kind of component-specific memory is created and
+image, the shopping cart. In ReactPy, this kind of component-specific memory is created and
updated with a "hook" called ``use_state()`` that creates a **state variable** and
**state setter** respectively:
-.. idom:: adding-interactivity/components-with-state/_examples/adding_state_variable
+.. reactpy:: guides/adding-interactivity/components-with-state/_examples/adding_state_variable
-In IDOM, ``use_state``, as well as any other function whose name starts with ``use``, is
-called a "hook". These are special functions that should only be called while IDOM is
+In ReactPy, ``use_state``, as well as any other function whose name starts with ``use``, is
+called a "hook". These are special functions that should only be called while ReactPy is
:ref:`rendering `. They let you "hook into" the different
-capabilities of IDOM's components of which ``use_state`` is just one (well get into the
+capabilities of ReactPy's components of which ``use_state`` is just one (well get into the
other :ref:`later `).
.. card::
- :link: adding-interactivity/index
+ :link: guides/adding-interactivity/index
:link-type: doc
:octicon:`book` Read More
@@ -168,7 +169,7 @@ Chapter 4 - :ref:`Managing State`
---------------------------------
.. card::
- :link: managing-state/index
+ :link: guides/managing-state/index
:link-type: doc
:octicon:`book` Read More
@@ -182,7 +183,7 @@ Chapter 5 - :ref:`Escape Hatches`
---------------------------------
.. card::
- :link: escape-hatches/index
+ :link: guides/escape-hatches/index
:link-type: doc
:octicon:`book` Read More
@@ -191,11 +192,11 @@ Chapter 5 - :ref:`Escape Hatches`
Under construction đ§
-Chapter 6 - :ref:`Understanding IDOM`
--------------------------------------
+Chapter 6 - :ref:`Understanding ReactPy`
+----------------------------------------
.. card::
- :link: escape-hatches/index
+ :link: guides/escape-hatches/index
:link-type: doc
:octicon:`book` Read More
diff --git a/docs/source/managing-state/index.rst b/docs/source/managing-state/index.rst
deleted file mode 100644
index 4ef9850ac..000000000
--- a/docs/source/managing-state/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-Managing State
-==============
-
-.. toctree::
- :hidden:
-
- keeping-components-pure
- logical-flow-of-state
- structuring-your-state
- shared-component-state
- when-to-reset-state
- writing-tests
-
-Under construction đ§
diff --git a/docs/source/managing-state/keeping-components-pure.rst b/docs/source/managing-state/keeping-components-pure.rst
deleted file mode 100644
index a2fc1a15b..000000000
--- a/docs/source/managing-state/keeping-components-pure.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _Keeping Components Pure:
-
-Keeping Components Pure đ§
-==========================
-
-.. note::
-
- Under construction đ§
diff --git a/docs/source/managing-state/logical-flow-of-state.rst b/docs/source/managing-state/logical-flow-of-state.rst
deleted file mode 100644
index 53bf0cff9..000000000
--- a/docs/source/managing-state/logical-flow-of-state.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _Logical Flow of State:
-
-Logical Flow of State đ§
-========================
-
-.. note::
-
- Under construction đ§
diff --git a/docs/source/reference-material/_examples/click_count.py b/docs/source/reference-material/_examples/click_count.py
deleted file mode 100644
index 6f30ce517..000000000
--- a/docs/source/reference-material/_examples/click_count.py
+++ /dev/null
@@ -1,14 +0,0 @@
-import idom
-
-
-@idom.component
-def ClickCount():
- count, set_count = idom.hooks.use_state(0)
-
- return idom.html.button(
- {"onClick": lambda event: set_count(count + 1)},
- [f"Click count: {count}"],
- )
-
-
-idom.run(ClickCount)
diff --git a/docs/source/reference-material/_examples/material_ui_switch.py b/docs/source/reference-material/_examples/material_ui_switch.py
deleted file mode 100644
index 9e4363b74..000000000
--- a/docs/source/reference-material/_examples/material_ui_switch.py
+++ /dev/null
@@ -1,23 +0,0 @@
-import idom
-
-
-mui = idom.web.module_from_template("react", "@material-ui/core@^5.0", fallback="â")
-Switch = idom.web.export(mui, "Switch")
-
-
-@idom.component
-def DayNightSwitch():
- checked, set_checked = idom.hooks.use_state(False)
-
- return idom.html.div(
- Switch(
- {
- "checked": checked,
- "onChange": lambda event, checked: set_checked(checked),
- }
- ),
- "đ" if checked else "đ",
- )
-
-
-idom.run(DayNightSwitch)
diff --git a/docs/source/reference-material/_examples/todo.py b/docs/source/reference-material/_examples/todo.py
deleted file mode 100644
index 7b1f6f675..000000000
--- a/docs/source/reference-material/_examples/todo.py
+++ /dev/null
@@ -1,33 +0,0 @@
-import idom
-
-
-@idom.component
-def Todo():
- items, set_items = idom.hooks.use_state([])
-
- async def add_new_task(event):
- if event["key"] == "Enter":
- set_items(items + [event["target"]["value"]])
-
- tasks = []
-
- for index, text in enumerate(items):
-
- async def remove_task(event, index=index):
- set_items(items[:index] + items[index + 1 :])
-
- task_text = idom.html.td(idom.html.p(text))
- delete_button = idom.html.td({"onClick": remove_task}, idom.html.button(["x"]))
- tasks.append(idom.html.tr(task_text, delete_button))
-
- task_input = idom.html.input({"onKeyDown": add_new_task})
- task_table = idom.html.table(tasks)
-
- return idom.html.div(
- idom.html.p("press enter to add a task:"),
- task_input,
- task_table,
- )
-
-
-idom.run(Todo)
diff --git a/docs/source/reference-material/_examples/use_reducer_counter.py b/docs/source/reference-material/_examples/use_reducer_counter.py
deleted file mode 100644
index ea1b780a0..000000000
--- a/docs/source/reference-material/_examples/use_reducer_counter.py
+++ /dev/null
@@ -1,26 +0,0 @@
-import idom
-
-
-def reducer(count, action):
- if action == "increment":
- return count + 1
- elif action == "decrement":
- return count - 1
- elif action == "reset":
- return 0
- else:
- raise ValueError(f"Unknown action '{action}'")
-
-
-@idom.component
-def Counter():
- count, dispatch = idom.hooks.use_reducer(reducer, 0)
- return idom.html.div(
- f"Count: {count}",
- idom.html.button({"onClick": lambda event: dispatch("reset")}, "Reset"),
- idom.html.button({"onClick": lambda event: dispatch("increment")}, "+"),
- idom.html.button({"onClick": lambda event: dispatch("decrement")}, "-"),
- )
-
-
-idom.run(Counter)
diff --git a/docs/source/reference-material/_examples/use_state_counter.py b/docs/source/reference-material/_examples/use_state_counter.py
deleted file mode 100644
index 8626a60b9..000000000
--- a/docs/source/reference-material/_examples/use_state_counter.py
+++ /dev/null
@@ -1,24 +0,0 @@
-import idom
-
-
-def increment(last_count):
- return last_count + 1
-
-
-def decrement(last_count):
- return last_count - 1
-
-
-@idom.component
-def Counter():
- initial_count = 0
- count, set_count = idom.hooks.use_state(initial_count)
- return idom.html.div(
- f"Count: {count}",
- idom.html.button({"onClick": lambda event: set_count(initial_count)}, "Reset"),
- idom.html.button({"onClick": lambda event: set_count(increment)}, "+"),
- idom.html.button({"onClick": lambda event: set_count(decrement)}, "-"),
- )
-
-
-idom.run(Counter)
diff --git a/docs/source/reference-material/_examples/victory_chart.py b/docs/source/reference-material/_examples/victory_chart.py
deleted file mode 100644
index e2c48d34e..000000000
--- a/docs/source/reference-material/_examples/victory_chart.py
+++ /dev/null
@@ -1,8 +0,0 @@
-import idom
-
-
-victory = idom.web.module_from_template("react", "victory-bar", fallback="â")
-VictoryBar = idom.web.export(victory, "VictoryBar")
-
-bar_style = {"parent": {"width": "500px"}, "data": {"fill": "royalblue"}}
-idom.run(idom.component(lambda: VictoryBar({"style": bar_style})))
diff --git a/docs/source/reference-material/examples.rst b/docs/source/reference-material/examples.rst
deleted file mode 100644
index 694864e53..000000000
--- a/docs/source/reference-material/examples.rst
+++ /dev/null
@@ -1,106 +0,0 @@
-Examples
-========
-
-Slideshow
----------
-
-Try clicking the image đąī¸
-
-.. idom:: _examples/slideshow
- :result-is-default-tab:
-
-
-Click Counter
--------------
-
-.. idom:: _examples/click_count
- :result-is-default-tab:
-
-
-To Do List
-----------
-
-Try typing in the text box and pressing 'Enter' đ
-
-.. idom:: _examples/todo
- :result-is-default-tab:
-
-
-Simple Image Movement
----------------------
-
-.. idom:: _examples/character_movement
- :result-is-default-tab:
-
-
-The Game Snake
---------------
-
-Click to start playing and use the arrow keys to move đŽ
-
-Slow internet may cause inconsistent frame pacing đ
-
-.. idom:: _examples/snake_game
- :result-is-default-tab:
-
-
-Matplotlib Plot
----------------
-
-Pick the polynomial coefficients (separate each coefficient by a space) đĸ:
-
-.. idom:: _examples/matplotlib_plot
- :result-is-default-tab:
-
-
-Simple Dashboard
-----------------
-
-Try interacting with the sliders đ
-
-.. idom:: _examples/simple_dashboard
- :result-is-default-tab:
-
-
-Dynamically Loaded React Components
------------------------------------
-
-This method is not recommended for use in production applications, but it's great while
-you're experimenting:
-
-.. idom:: _examples/victory_chart
- :result-is-default-tab:
-
-
-Material UI Button
-------------------
-
-Click the button to change the indicator đ
-
-.. idom:: _examples/material_ui_switch
- :result-is-default-tab:
-
-
-Pigeon Maps
------------
-
-Click the map to create pinned location đ:
-
-.. idom:: _examples/pigeon_maps
- :result-is-default-tab:
-
-
-Cytoscape Network Graph
------------------------
-
-You can move the nodes in the graph đ¸ī¸:
-
-.. idom:: _examples/network_graph
- :result-is-default-tab:
-
-
-.. Links
-.. =====
-
-.. |launch-binder| image:: https://mybinder.org/badge_logo.svg
- :target: https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=examples%2Fintroduction.ipynb
diff --git a/docs/source/reference-material/faq.rst b/docs/source/reference-material/faq.rst
deleted file mode 100644
index df1628dcd..000000000
--- a/docs/source/reference-material/faq.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-FAQ
-===
-
-See our :discussion-type:`Discussion Forum ` for more questions and answers.
-
-
-Do UI components run client-side?
----------------------------------
-
-No. The layout is constructed, and components are executed, server-side in Python. Only
-rendering occurs client-side. This means you can access files, databases, and all your
-favorite Python packages with IDOM.
-
-
-Does IDOM transpile Python to Javascript?
------------------------------------------
-
-No. As in the answer to :ref:`Do UI components run client-side?`, IDOM runs almost
-everything server-side and in Python. This was an explicit design choice to keep things
-simple and one which allows you to do everything you normally would in Python.
-
-
-Does IDOM support any React component?
---------------------------------------
-
-If you use :ref:`Dynamically Loaded Components`, then the answer is no. Only components
-whose props are JSON serializable, or which expect basic callback functions similar to
-those of standard event handlers (e.g. ``onClick``) will operate as expected.
-
-However, if you import a :ref:`Custom Javascript Component `
-then, so long as the bundle has be defined appropriately, any component can be made to
-work, even those that don't rely on React.
-
-
-How does IDOM communicate with the client?
-------------------------------------------
-
-IDOM sends diffs of a Virtual Document Object Model (:ref:`VDOM`) to the
-client. For more details, see the description in
-`this article `__.
-
-
-Can I use Javascript components from a CDN?
--------------------------------------------
-
-Yes, but with some restrictions:
-
-1. The Javascript in question must be distributed as an ECMAScript Module
- (`ESM `__)
-2. The module must export the :ref:`required interface `.
-
-These restrictions apply because the Javascript from the CDN must be able to run
-natively in the browser and the module must be able to run in isolation from the main
-application.
-
-See :ref:`Distributing Javascript via CDN_` for more info.
-
-
-What props can I pass to Javascript components?
------------------------------------------------
-
-You can only pass JSON serializable props to components implemented in Javascript. It is
-possible to create a :ref:`Custom Javascript Component `
-which undestands how to deserialise JSON data into native Javascript objects though.
diff --git a/docs/source/reference-material/index.rst b/docs/source/reference-material/index.rst
deleted file mode 100644
index fb4021aca..000000000
--- a/docs/source/reference-material/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-Reference Material
-==================
-
-.. toctree::
- :hidden:
-
- examples
- hooks-api
- /_auto/apis
- javascript-api
- browser-events
- specifications
- faq
-
-.. note::
-
- Under construction đ§
diff --git a/docs/source/reference-material/_examples/character_movement/app.py b/docs/source/reference/_examples/character_movement/main.py
similarity index 64%
rename from docs/source/reference-material/_examples/character_movement/app.py
rename to docs/source/reference/_examples/character_movement/main.py
index fbf257a32..9545b0c0a 100644
--- a/docs/source/reference-material/_examples/character_movement/app.py
+++ b/docs/source/reference/_examples/character_movement/main.py
@@ -1,9 +1,8 @@
from pathlib import Path
from typing import NamedTuple
-from idom import component, html, run, use_state
-from idom.widgets import image
-
+from reactpy import component, html, run, use_state
+from reactpy.widgets import image
HERE = Path(__file__)
CHARACTER_IMAGE = (HERE.parent / "static" / "bunny.png").read_bytes()
@@ -42,7 +41,7 @@ def Scene():
"style": {
"width": "200px",
"height": "200px",
- "backgroundColor": "slategray",
+ "background_color": "slategray",
}
},
image(
@@ -58,12 +57,16 @@ def Scene():
},
),
),
- html.button({"onClick": lambda e: set_position(translate(x=-10))}, "Move Left"),
- html.button({"onClick": lambda e: set_position(translate(x=10))}, "Move Right"),
- html.button({"onClick": lambda e: set_position(translate(y=-10))}, "Move Up"),
- html.button({"onClick": lambda e: set_position(translate(y=10))}, "Move Down"),
- html.button({"onClick": lambda e: set_position(rotate(-30))}, "Rotate Left"),
- html.button({"onClick": lambda e: set_position(rotate(30))}, "Rotate Right"),
+ html.button(
+ {"on_click": lambda e: set_position(translate(x=-10))}, "Move Left"
+ ),
+ html.button(
+ {"on_click": lambda e: set_position(translate(x=10))}, "Move Right"
+ ),
+ html.button({"on_click": lambda e: set_position(translate(y=-10))}, "Move Up"),
+ html.button({"on_click": lambda e: set_position(translate(y=10))}, "Move Down"),
+ html.button({"on_click": lambda e: set_position(rotate(-30))}, "Rotate Left"),
+ html.button({"on_click": lambda e: set_position(rotate(30))}, "Rotate Right"),
)
diff --git a/docs/source/reference-material/_examples/character_movement/static/bunny.png b/docs/source/reference/_examples/character_movement/static/bunny.png
similarity index 100%
rename from docs/source/reference-material/_examples/character_movement/static/bunny.png
rename to docs/source/reference/_examples/character_movement/static/bunny.png
diff --git a/docs/source/reference/_examples/click_count.py b/docs/source/reference/_examples/click_count.py
new file mode 100644
index 000000000..3ee2c89c5
--- /dev/null
+++ b/docs/source/reference/_examples/click_count.py
@@ -0,0 +1,13 @@
+import reactpy
+
+
+@reactpy.component
+def ClickCount():
+ count, set_count = reactpy.hooks.use_state(0)
+
+ return reactpy.html.button(
+ {"on_click": lambda event: set_count(count + 1)}, [f"Click count: {count}"]
+ )
+
+
+reactpy.run(ClickCount)
diff --git a/docs/source/reference/_examples/material_ui_switch.py b/docs/source/reference/_examples/material_ui_switch.py
new file mode 100644
index 000000000..704ae3145
--- /dev/null
+++ b/docs/source/reference/_examples/material_ui_switch.py
@@ -0,0 +1,22 @@
+import reactpy
+
+mui = reactpy.web.module_from_template("react", "@material-ui/core@^5.0", fallback="â")
+Switch = reactpy.web.export(mui, "Switch")
+
+
+@reactpy.component
+def DayNightSwitch():
+ checked, set_checked = reactpy.hooks.use_state(False)
+
+ return reactpy.html.div(
+ Switch(
+ {
+ "checked": checked,
+ "onChange": lambda event, checked: set_checked(checked),
+ }
+ ),
+ "đ" if checked else "đ",
+ )
+
+
+reactpy.run(DayNightSwitch)
diff --git a/docs/source/reference-material/_examples/matplotlib_plot.py b/docs/source/reference/_examples/matplotlib_plot.py
similarity index 62%
rename from docs/source/reference-material/_examples/matplotlib_plot.py
rename to docs/source/reference/_examples/matplotlib_plot.py
index 6dffb79db..5c4d616fe 100644
--- a/docs/source/reference-material/_examples/matplotlib_plot.py
+++ b/docs/source/reference/_examples/matplotlib_plot.py
@@ -2,24 +2,24 @@
import matplotlib.pyplot as plt
-import idom
-from idom.widgets import image
+import reactpy
+from reactpy.widgets import image
-@idom.component
+@reactpy.component
def PolynomialPlot():
- coefficients, set_coefficients = idom.hooks.use_state([0])
+ coefficients, set_coefficients = reactpy.hooks.use_state([0])
- x = [n for n in linspace(-1, 1, 50)]
+ x = list(linspace(-1, 1, 50))
y = [polynomial(value, coefficients) for value in x]
- return idom.html.div(
+ return reactpy.html.div(
plot(f"{len(coefficients)} Term Polynomial", x, y),
ExpandableNumberInputs(coefficients, set_coefficients),
)
-@idom.component
+@reactpy.component
def ExpandableNumberInputs(values, set_values):
inputs = []
for i in range(len(values)):
@@ -31,16 +31,16 @@ def set_value_at_index(event, index=i):
inputs.append(poly_coef_input(i + 1, set_value_at_index))
def add_input():
- set_values(values + [0])
+ set_values([*values, 0])
def del_input():
set_values(values[:-1])
- return idom.html.div(
- idom.html.div(
+ return reactpy.html.div(
+ reactpy.html.div(
"add/remove term:",
- idom.html.button({"onClick": lambda event: add_input()}, "+"),
- idom.html.button({"onClick": lambda event: del_input()}, "-"),
+ reactpy.html.button({"on_click": lambda event: add_input()}, "+"),
+ reactpy.html.button({"on_click": lambda event: del_input()}, "-"),
),
inputs,
)
@@ -57,21 +57,15 @@ def plot(title, x, y):
def poly_coef_input(index, callback):
- return idom.html.div(
- {"style": {"margin-top": "5px"}},
- idom.html.label(
+ return reactpy.html.div(
+ {"style": {"margin-top": "5px"}, "key": index},
+ reactpy.html.label(
"C",
- idom.html.sub(index),
- " Ã X",
- idom.html.sup(index),
+ reactpy.html.sub(index),
+ " x X",
+ reactpy.html.sup(index),
),
- idom.html.input(
- {
- "type": "number",
- "onChange": callback,
- },
- ),
- key=index,
+ reactpy.html.input({"type": "number", "on_change": callback}),
)
@@ -88,4 +82,4 @@ def linspace(start, stop, n):
yield start + h * i
-idom.run(PolynomialPlot)
+reactpy.run(PolynomialPlot)
diff --git a/docs/source/reference-material/_examples/network_graph.py b/docs/source/reference/_examples/network_graph.py
similarity index 72%
rename from docs/source/reference-material/_examples/network_graph.py
rename to docs/source/reference/_examples/network_graph.py
index 3dfb9ae87..79b1092f3 100644
--- a/docs/source/reference-material/_examples/network_graph.py
+++ b/docs/source/reference/_examples/network_graph.py
@@ -1,19 +1,16 @@
import random
-import idom
+import reactpy
-
-react_cytoscapejs = idom.web.module_from_template(
- # we need to use this template because react-cytoscapejs uses a default export
+react_cytoscapejs = reactpy.web.module_from_template(
"react",
"react-cytoscapejs",
- exports_default=True,
fallback="â",
)
-Cytoscape = idom.web.export(react_cytoscapejs, "default")
+Cytoscape = reactpy.web.export(react_cytoscapejs, "default")
-@idom.component
+@reactpy.component
def RandomNetworkGraph():
return Cytoscape(
{
@@ -40,4 +37,4 @@ def random_network(number_of_nodes):
return nodes + conns
-idom.run(RandomNetworkGraph)
+reactpy.run(RandomNetworkGraph)
diff --git a/docs/source/reference-material/_examples/pigeon_maps.py b/docs/source/reference/_examples/pigeon_maps.py
similarity index 52%
rename from docs/source/reference-material/_examples/pigeon_maps.py
rename to docs/source/reference/_examples/pigeon_maps.py
index ab0157f73..1ddf04fdc 100644
--- a/docs/source/reference-material/_examples/pigeon_maps.py
+++ b/docs/source/reference/_examples/pigeon_maps.py
@@ -1,26 +1,23 @@
-import idom
+import reactpy
+pigeon_maps = reactpy.web.module_from_template("react", "pigeon-maps", fallback="â")
+Map, Marker = reactpy.web.export(pigeon_maps, ["Map", "Marker"])
-pigeon_maps = idom.web.module_from_template("react", "pigeon-maps", fallback="â")
-Map, Marker = idom.web.export(pigeon_maps, ["Map", "Marker"])
-
-@idom.component
+@reactpy.component
def MapWithMarkers():
marker_anchor, add_marker_anchor, remove_marker_anchor = use_set()
- markers = list(
- map(
- lambda anchor: Marker(
- {
- "anchor": anchor,
- "onClick": lambda: remove_marker_anchor(anchor),
- },
- key=str(anchor),
- ),
- marker_anchor,
+ markers = [
+ Marker(
+ {
+ "anchor": anchor,
+ "onClick": lambda event, a=anchor: remove_marker_anchor(a),
+ },
+ key=str(anchor),
)
- )
+ for anchor in marker_anchor
+ ]
return Map(
{
@@ -35,7 +32,7 @@ def MapWithMarkers():
def use_set(initial_value=None):
- values, set_values = idom.hooks.use_state(initial_value or set())
+ values, set_values = reactpy.hooks.use_state(initial_value or set())
def add_value(lat_lon):
set_values(values.union({lat_lon}))
@@ -46,4 +43,4 @@ def remove_value(lat_lon):
return values, add_value, remove_value
-idom.run(MapWithMarkers)
+reactpy.run(MapWithMarkers)
diff --git a/docs/source/reference-material/_examples/simple_dashboard.py b/docs/source/reference/_examples/simple_dashboard.py
similarity index 73%
rename from docs/source/reference-material/_examples/simple_dashboard.py
rename to docs/source/reference/_examples/simple_dashboard.py
index 540082f58..66913fc84 100644
--- a/docs/source/reference-material/_examples/simple_dashboard.py
+++ b/docs/source/reference/_examples/simple_dashboard.py
@@ -2,28 +2,27 @@
import random
import time
-import idom
-from idom.widgets import Input
+import reactpy
+from reactpy.widgets import Input
-
-victory = idom.web.module_from_template(
+victory = reactpy.web.module_from_template(
"react",
"victory-line",
fallback="â",
# not usually required (see issue #461 for more info)
unmount_before_update=True,
)
-VictoryLine = idom.web.export(victory, "VictoryLine")
+VictoryLine = reactpy.web.export(victory, "VictoryLine")
-@idom.component
+@reactpy.component
def RandomWalk():
- mu = idom.hooks.use_ref(0)
- sigma = idom.hooks.use_ref(1)
+ mu = reactpy.hooks.use_ref(0)
+ sigma = reactpy.hooks.use_ref(1)
- return idom.html.div(
+ return reactpy.html.div(
RandomWalkGraph(mu, sigma),
- idom.html.style(
+ reactpy.html.style(
"""
.number-input-container {margin-bottom: 20px}
.number-input-container input {width: 48%;float: left}
@@ -45,12 +44,12 @@ def RandomWalk():
)
-@idom.component
+@reactpy.component
def RandomWalkGraph(mu, sigma):
interval = use_interval(0.5)
- data, set_data = idom.hooks.use_state([{"x": 0, "y": 0}] * 50)
+ data, set_data = reactpy.hooks.use_state([{"x": 0, "y": 0}] * 50)
- @idom.hooks.use_effect
+ @reactpy.hooks.use_effect
async def animate():
await interval
last_data_point = data[-1]
@@ -71,27 +70,27 @@ async def animate():
)
-@idom.component
+@reactpy.component
def NumberInput(label, value, set_value_callback, domain):
minimum, maximum, step = domain
attrs = {"min": minimum, "max": maximum, "step": step}
- value, set_value = idom.hooks.use_state(value)
+ value, set_value = reactpy.hooks.use_state(value)
def update_value(value):
set_value(value)
set_value_callback(value)
- return idom.html.fieldset(
- {"class": "number-input-container"},
- idom.html.legend({"style": {"font-size": "medium"}}, label),
+ return reactpy.html.fieldset(
+ {"class_name": "number-input-container"},
+ reactpy.html.legend({"style": {"font-size": "medium"}}, label),
Input(update_value, "number", value, attributes=attrs, cast=float),
Input(update_value, "range", value, attributes=attrs, cast=float),
)
def use_interval(rate):
- usage_time = idom.hooks.use_ref(time.time())
+ usage_time = reactpy.hooks.use_ref(time.time())
async def interval() -> None:
await asyncio.sleep(rate - (time.time() - usage_time.current))
@@ -100,4 +99,4 @@ async def interval() -> None:
return asyncio.ensure_future(interval())
-idom.run(RandomWalk)
+reactpy.run(RandomWalk)
diff --git a/docs/source/reference-material/_examples/slideshow.py b/docs/source/reference/_examples/slideshow.py
similarity index 55%
rename from docs/source/reference-material/_examples/slideshow.py
rename to docs/source/reference/_examples/slideshow.py
index 0d3116ac4..b490b3feb 100644
--- a/docs/source/reference-material/_examples/slideshow.py
+++ b/docs/source/reference/_examples/slideshow.py
@@ -1,20 +1,20 @@
-import idom
+import reactpy
-@idom.component
+@reactpy.component
def Slideshow():
- index, set_index = idom.hooks.use_state(0)
+ index, set_index = reactpy.hooks.use_state(0)
def next_image(event):
set_index(index + 1)
- return idom.html.img(
+ return reactpy.html.img(
{
"src": f"https://picsum.photos/id/{index}/800/300",
"style": {"cursor": "pointer"},
- "onClick": next_image,
+ "on_click": next_image,
}
)
-idom.run(Slideshow)
+reactpy.run(Slideshow)
diff --git a/docs/source/reference-material/_examples/snake_game.py b/docs/source/reference/_examples/snake_game.py
similarity index 74%
rename from docs/source/reference-material/_examples/snake_game.py
rename to docs/source/reference/_examples/snake_game.py
index 92fe054f0..36916410e 100644
--- a/docs/source/reference-material/_examples/snake_game.py
+++ b/docs/source/reference/_examples/snake_game.py
@@ -3,7 +3,7 @@
import random
import time
-import idom
+import reactpy
class GameState(enum.Enum):
@@ -13,26 +13,25 @@ class GameState(enum.Enum):
play = 3
-@idom.component
+@reactpy.component
def GameView():
- game_state, set_game_state = idom.hooks.use_state(GameState.init)
+ game_state, set_game_state = reactpy.hooks.use_state(GameState.init)
if game_state == GameState.play:
return GameLoop(grid_size=6, block_scale=50, set_game_state=set_game_state)
- start_button = idom.html.button(
- {"onClick": lambda event: set_game_state(GameState.play)},
- "Start",
+ start_button = reactpy.html.button(
+ {"on_click": lambda event: set_game_state(GameState.play)}, "Start"
)
if game_state == GameState.won:
- menu = idom.html.div(idom.html.h3("You won!"), start_button)
+ menu = reactpy.html.div(reactpy.html.h3("You won!"), start_button)
elif game_state == GameState.lost:
- menu = idom.html.div(idom.html.h3("You lost"), start_button)
+ menu = reactpy.html.div(reactpy.html.h3("You lost"), start_button)
else:
- menu = idom.html.div(idom.html.h3("Click to play"), start_button)
+ menu = reactpy.html.div(reactpy.html.h3("Click to play"), start_button)
- menu_style = idom.html.style(
+ menu_style = reactpy.html.style(
"""
.snake-game-menu h3 {
margin-top: 0px !important;
@@ -40,7 +39,7 @@ def GameView():
"""
)
- return idom.html.div({"className": "snake-game-menu"}, menu_style, menu)
+ return reactpy.html.div({"class_name": "snake-game-menu"}, menu_style, menu)
class Direction(enum.Enum):
@@ -50,19 +49,21 @@ class Direction(enum.Enum):
ArrowRight = (1, 0)
-@idom.component
+@reactpy.component
def GameLoop(grid_size, block_scale, set_game_state):
# we `use_ref` here to capture the latest direction press without any delay
- direction = idom.hooks.use_ref(Direction.ArrowRight.value)
+ direction = reactpy.hooks.use_ref(Direction.ArrowRight.value)
# capture the last direction of travel that was rendered
last_direction = direction.current
- snake, set_snake = idom.hooks.use_state([(grid_size // 2 - 1, grid_size // 2 - 1)])
+ snake, set_snake = reactpy.hooks.use_state(
+ [(grid_size // 2 - 1, grid_size // 2 - 1)]
+ )
food, set_food = use_snake_food(grid_size, snake)
grid = create_grid(grid_size, block_scale)
- @idom.event(prevent_default=True)
+ @reactpy.event(prevent_default=True)
def on_direction_change(event):
if hasattr(Direction, event["key"]):
maybe_new_direction = Direction[event["key"]].value
@@ -72,7 +73,7 @@ def on_direction_change(event):
if direction_vector_sum != (0, 0):
direction.current = maybe_new_direction
- grid_wrapper = idom.html.div({"onKeyDown": on_direction_change}, grid)
+ grid_wrapper = reactpy.html.div({"on_key_down": on_direction_change}, grid)
assign_grid_block_color(grid, food, "blue")
@@ -89,7 +90,7 @@ def on_direction_change(event):
interval = use_interval(0.5)
- @idom.hooks.use_effect
+ @reactpy.hooks.use_effect
async def animate():
if new_game_state is not None:
await asyncio.sleep(1)
@@ -106,7 +107,7 @@ async def animate():
if snake[-1] == food:
set_food()
- new_snake = snake + [new_snake_head]
+ new_snake = [*snake, new_snake_head]
else:
new_snake = snake[1:] + [new_snake_head]
@@ -119,7 +120,7 @@ def use_snake_food(grid_size, current_snake):
grid_points = {(x, y) for x in range(grid_size) for y in range(grid_size)}
points_not_in_snake = grid_points.difference(current_snake)
- food, _set_food = idom.hooks.use_state(current_snake[-1])
+ food, _set_food = reactpy.hooks.use_state(current_snake[-1])
def set_food():
_set_food(random.choice(list(points_not_in_snake)))
@@ -128,7 +129,7 @@ def set_food():
def use_interval(rate):
- usage_time = idom.hooks.use_ref(time.time())
+ usage_time = reactpy.hooks.use_ref(time.time())
async def interval() -> None:
await asyncio.sleep(rate - (time.time() - usage_time.current))
@@ -138,7 +139,7 @@ async def interval() -> None:
def create_grid(grid_size, block_scale):
- return idom.html.div(
+ return reactpy.html.div(
{
"style": {
"height": f"{block_scale * grid_size}px",
@@ -149,16 +150,15 @@ def create_grid(grid_size, block_scale):
"grid-template-columns": f"repeat({grid_size}, {block_scale}px)",
"grid-template-rows": f"repeat({grid_size}, {block_scale}px)",
},
- "tabIndex": -1,
+ "tab_index": -1,
},
[
- idom.html.div(
- {"style": {"height": f"{block_scale}px"}},
+ reactpy.html.div(
+ {"style": {"height": f"{block_scale}px"}, "key": i},
[
create_grid_block("black", block_scale, key=i)
for i in range(grid_size)
],
- key=i,
)
for i in range(grid_size)
],
@@ -166,16 +166,16 @@ def create_grid(grid_size, block_scale):
def create_grid_block(color, block_scale, key):
- return idom.html.div(
+ return reactpy.html.div(
{
"style": {
"height": f"{block_scale}px",
"width": f"{block_scale}px",
- "backgroundColor": color,
+ "background_color": color,
"outline": "1px solid grey",
- }
- },
- key=key,
+ },
+ "key": key,
+ }
)
@@ -185,4 +185,4 @@ def assign_grid_block_color(grid, point, color):
block["attributes"]["style"]["backgroundColor"] = color
-idom.run(GameView)
+reactpy.run(GameView)
diff --git a/docs/source/reference/_examples/todo.py b/docs/source/reference/_examples/todo.py
new file mode 100644
index 000000000..104ea59a9
--- /dev/null
+++ b/docs/source/reference/_examples/todo.py
@@ -0,0 +1,35 @@
+import reactpy
+
+
+@reactpy.component
+def Todo():
+ items, set_items = reactpy.hooks.use_state([])
+
+ async def add_new_task(event):
+ if event["key"] == "Enter":
+ set_items([*items, event["target"]["value"]])
+
+ tasks = []
+
+ for index, text in enumerate(items):
+
+ async def remove_task(event, index=index):
+ set_items(items[:index] + items[index + 1 :])
+
+ task_text = reactpy.html.td(reactpy.html.p(text))
+ delete_button = reactpy.html.td(
+ {"on_click": remove_task}, reactpy.html.button(["x"])
+ )
+ tasks.append(reactpy.html.tr(task_text, delete_button))
+
+ task_input = reactpy.html.input({"on_key_down": add_new_task})
+ task_table = reactpy.html.table(tasks)
+
+ return reactpy.html.div(
+ reactpy.html.p("press enter to add a task:"),
+ task_input,
+ task_table,
+ )
+
+
+reactpy.run(Todo)
diff --git a/docs/source/reference/_examples/use_reducer_counter.py b/docs/source/reference/_examples/use_reducer_counter.py
new file mode 100644
index 000000000..6f9581dfd
--- /dev/null
+++ b/docs/source/reference/_examples/use_reducer_counter.py
@@ -0,0 +1,27 @@
+import reactpy
+
+
+def reducer(count, action):
+ if action == "increment":
+ return count + 1
+ elif action == "decrement":
+ return count - 1
+ elif action == "reset":
+ return 0
+ else:
+ msg = f"Unknown action '{action}'"
+ raise ValueError(msg)
+
+
+@reactpy.component
+def Counter():
+ count, dispatch = reactpy.hooks.use_reducer(reducer, 0)
+ return reactpy.html.div(
+ f"Count: {count}",
+ reactpy.html.button({"on_click": lambda event: dispatch("reset")}, "Reset"),
+ reactpy.html.button({"on_click": lambda event: dispatch("increment")}, "+"),
+ reactpy.html.button({"on_click": lambda event: dispatch("decrement")}, "-"),
+ )
+
+
+reactpy.run(Counter)
diff --git a/docs/source/reference/_examples/use_state_counter.py b/docs/source/reference/_examples/use_state_counter.py
new file mode 100644
index 000000000..b2d8c84a9
--- /dev/null
+++ b/docs/source/reference/_examples/use_state_counter.py
@@ -0,0 +1,26 @@
+import reactpy
+
+
+def increment(last_count):
+ return last_count + 1
+
+
+def decrement(last_count):
+ return last_count - 1
+
+
+@reactpy.component
+def Counter():
+ initial_count = 0
+ count, set_count = reactpy.hooks.use_state(initial_count)
+ return reactpy.html.div(
+ f"Count: {count}",
+ reactpy.html.button(
+ {"on_click": lambda event: set_count(initial_count)}, "Reset"
+ ),
+ reactpy.html.button({"on_click": lambda event: set_count(increment)}, "+"),
+ reactpy.html.button({"on_click": lambda event: set_count(decrement)}, "-"),
+ )
+
+
+reactpy.run(Counter)
diff --git a/docs/source/reference/_examples/victory_chart.py b/docs/source/reference/_examples/victory_chart.py
new file mode 100644
index 000000000..ce37c522f
--- /dev/null
+++ b/docs/source/reference/_examples/victory_chart.py
@@ -0,0 +1,7 @@
+import reactpy
+
+victory = reactpy.web.module_from_template("react", "victory-bar", fallback="â")
+VictoryBar = reactpy.web.export(victory, "VictoryBar")
+
+bar_style = {"parent": {"width": "500px"}, "data": {"fill": "royalblue"}}
+reactpy.run(reactpy.component(lambda: VictoryBar({"style": bar_style})))
diff --git a/docs/source/reference-material/_static/vdom-json-schema.json b/docs/source/reference/_static/vdom-json-schema.json
similarity index 83%
rename from docs/source/reference-material/_static/vdom-json-schema.json
rename to docs/source/reference/_static/vdom-json-schema.json
index d3ab5bd6d..b1005d2ed 100644
--- a/docs/source/reference-material/_static/vdom-json-schema.json
+++ b/docs/source/reference/_static/vdom-json-schema.json
@@ -35,9 +35,7 @@
"type": "string"
}
},
- "required": [
- "tagName"
- ],
+ "required": ["tagName"],
"type": "object"
},
"elementChildren": {
@@ -61,12 +59,9 @@
"then": {
"$ref": "#/definitions/element"
},
- "type": [
- "object",
- "string"
- ]
+ "type": ["object", "string"]
},
- "eventHander": {
+ "eventHandler": {
"properties": {
"preventDefault": {
"type": "boolean"
@@ -78,9 +73,7 @@
"type": "string"
}
},
- "required": [
- "target"
- ],
+ "required": ["target"],
"type": "object"
},
"importSource": {
@@ -94,29 +87,20 @@
"then": {
"$ref": "#/definitions/elementOrString"
},
- "type": [
- "object",
- "string",
- "null"
- ]
+ "type": ["object", "string", "null"]
},
"source": {
"type": "string"
},
"sourceType": {
- "enum": [
- "URL",
- "NAME"
- ]
+ "enum": ["URL", "NAME"]
},
"unmountBeforeUpdate": {
"type": "boolean"
}
},
- "required": [
- "source"
- ],
+ "required": ["source"],
"type": "object"
}
}
-}
\ No newline at end of file
+}
diff --git a/docs/source/reference-material/browser-events.rst b/docs/source/reference/browser-events.rst
similarity index 100%
rename from docs/source/reference-material/browser-events.rst
rename to docs/source/reference/browser-events.rst
diff --git a/docs/source/reference-material/hooks-api.rst b/docs/source/reference/hooks-api.rst
similarity index 85%
rename from docs/source/reference-material/hooks-api.rst
rename to docs/source/reference/hooks-api.rst
index f2967376e..ca8123e85 100644
--- a/docs/source/reference-material/hooks-api.rst
+++ b/docs/source/reference/hooks-api.rst
@@ -7,12 +7,6 @@ Components. Their usage should always follow the :ref:`Rules of Hooks`. For most
cases the :ref:`Basic Hooks` should be enough, however the remaining
:ref:`Supplementary Hooks` should fulfill less common scenarios.
-.. note::
-
- Not all of React's built-in hooks have been implemented.
- `In the future `_ they will be
- added, but if you have a particular need for a missing hook post an issue.
-
Basic Hooks
===========
@@ -55,7 +49,7 @@ accepts a single argument (the previous state) and returns the next state. Consi
simply use case of a counter where we've pulled out logic for increment and
decremented the count:
-.. idom:: _examples/use_state_counter
+.. reactpy:: _examples/use_state_counter
We use the functional form for the "+" and "-" buttons since the next ``count`` depends
on the previous value, while for the "Reset" button we simple assign the
@@ -108,7 +102,7 @@ component render functions.
.. note::
Normally in React the ``did_render`` function is called once an update has been
- committed to the screen. Since no such action is performed by IDOM, and the time
+ committed to the screen. Since no such action is performed by ReactPy, and the time
at which the update is displayed cannot be known we are unable to achieve parity
with this behavior.
@@ -159,16 +153,16 @@ Here, a new connection will be established whenever a new ``url`` is set.
Async Effects
.............
-A behavior unique to IDOM's implementation of ``use_effect`` is that it natively
+A behavior unique to ReactPy's implementation of ``use_effect`` is that it natively
supports ``async`` functions:
.. code-block::
- async def nonblocking_effect():
+ async def non_blocking_effect():
resource = await do_something_asynchronously()
return lambda: blocking_close(resource)
- use_effect(nonblocking_effect)
+ use_effect(non_blocking_effect)
There are **three important subtleties** to note about using asynchronous effects:
@@ -186,9 +180,9 @@ There are **three important subtleties** to note about using asynchronous effect
Manual Effect Conditions
........................
-In some cases, you may want to explicitely declare when an effect should be triggered.
-You can do this by passing ``dependencies`` to ``use_effect``. Each of the following values
-produce different effect behaviors:
+In some cases, you may want to explicitly declare when an effect should be triggered.
+You can do this by passing ``dependencies`` to ``use_effect``. Each of the following
+values produce different effect behaviors:
- ``use_effect(..., dependencies=None)`` - triggers and cleans up on every render.
- ``use_effect(..., dependencies=[])`` - only triggers on the first and cleans up after
@@ -197,6 +191,24 @@ produce different effect behaviors:
``x`` or ``y`` have changed.
+Use Context
+-----------
+
+.. code-block::
+
+ value = use_context(MyContext)
+
+Accepts a context object (the value returned from
+:func:`reactpy.core.hooks.create_context`) and returns the current context value for that
+context. The current context value is determined by the ``value`` argument passed to the
+nearest ``MyContext`` in the tree.
+
+When the nearest above the component updates, this Hook will
+trigger a rerender with the latest context value passed to that MyContext provider. Even
+if an ancestor uses React.memo or shouldComponentUpdate, a rerender will still happen
+starting at the component itself using useContext.
+
+
Supplementary Hooks
===================
@@ -223,7 +235,7 @@ may be slightly more performant as well as being preferable since there is only
We can rework the :ref:`Functional Updates` counter example to use ``use_reducer``:
-.. idom:: _examples/use_reducer_counter
+.. reactpy:: _examples/use_reducer_counter
.. note::
@@ -286,14 +298,13 @@ Use Ref
ref_container = use_ref(initial_value)
-Returns a mutable :class:`~idom.utils.Ref` object that has a single
-:attr:`~idom.utils.Ref.current` attribute that at first contains the ``initial_state``.
+Returns a mutable :class:`~reactpy.utils.Ref` object that has a single
+:attr:`~reactpy.utils.Ref.current` attribute that at first contains the ``initial_state``.
The identity of the ``Ref`` object will be preserved for the lifetime of the component.
A ``Ref`` is most useful if you need to incur side effects since updating its
``.current`` attribute doesn't trigger a re-render of the component. You'll often use this
hook alongside :ref:`Use Effect` or in response to component event handlers.
-:ref:`The Game Snake` provides a good use case for ``use_ref``.
.. links
@@ -318,7 +329,7 @@ Only call outside flow controls
**Don't call hooks inside loops, conditions, or nested functions.** Instead you must
always call hooks at the top level of your functions. By adhering to this rule you
ensure that hooks are always called in the exact same order. This fact is what allows
-IDOM to preserve the state of hooks between multiple calls to ``useState`` and
+ReactPy to preserve the state of hooks between multiple calls to ``useState`` and
``useEffect`` calls.
@@ -331,33 +342,33 @@ Only call in render functions
- â Call Hooks from another custom hook
-Following this rule ensures stateful logic for IDOM component is always clearly
+Following this rule ensures stateful logic for ReactPy component is always clearly
separated from the rest of your codebase.
Flake8 Plugin
-------------
-We provide a Flake8 plugin called `flake8-idom-hooks `_ that helps
+We provide a Flake8 plugin called `flake8-reactpy-hooks `_ that helps
to enforce the two rules described above. You can ``pip`` install it directly, or with
-the ``lint`` extra for IDOM:
+the ``lint`` extra for ReactPy:
.. code-block:: bash
- pip install flake8-idom-hooks
+ pip install flake8-reactpy-hooks
Once installed running, ``flake8`` on your code will start catching errors. For example:
.. code-block:: bash
- flake8 my_idom_components.py
+ flake8 my_reactpy_components.py
Might produce something like the following output:
.. code-block:: text
- ./my_idom_components:10:8 ROH102 hook 'use_effect' used inside if statement
- ./my_idom_components:23:4 ROH102 hook 'use_state' used outside component or hook definition
+ ./my_reactpy_components:10:8 ROH102 hook 'use_effect' used inside if statement
+ ./my_reactpy_components:23:4 ROH102 hook 'use_state' used outside component or hook definition
See the Flake8 docs for
`more info `__.
@@ -365,4 +376,4 @@ See the Flake8 docs for
.. links
.. =====
-.. _Flake8 Linter Plugin: https://github.com/idom-team/flake8-idom-hooks
+.. _Flake8 Linter Plugin: https://github.com/reactive-python/flake8-reactpy-hooks
diff --git a/docs/source/reference/html-attributes.rst b/docs/source/reference/html-attributes.rst
new file mode 100644
index 000000000..91813c355
--- /dev/null
+++ b/docs/source/reference/html-attributes.rst
@@ -0,0 +1,197 @@
+.. testcode::
+
+ from reactpy import html
+
+
+HTML Attributes
+===============
+
+In ReactPy, HTML attributes are specified using snake_case instead of dash-separated
+words. For example, ``tabindex`` and ``margin-left`` become ``tab_index`` and
+``margin_left`` respectively.
+
+
+Notable Attributes
+-------------------
+
+Some attributes in ReactPy are renamed, have special meaning, or are used differently
+than in HTML.
+
+``style``
+.........
+
+As mentioned above, instead of using a string to specify the ``style`` attribute, we use
+a dictionary to describe the CSS properties we want to apply to an element. For example,
+the following HTML:
+
+.. code-block:: html
+
+
+
My Todo List
+
+
Build a cool new app
+
Share it with the world!
+
+
+
+Would be written in ReactPy as:
+
+.. testcode::
+
+ html.div(
+ {
+ "style": {
+ "width": "50%",
+ "margin_left": "25%",
+ },
+ },
+ html.h1(
+ {
+ "style": {
+ "margin_top": "0px",
+ },
+ },
+ "My Todo List",
+ ),
+ html.ul(
+ html.li("Build a cool new app"),
+ html.li("Share it with the world!"),
+ ),
+ )
+
+``class`` vs ``class_name``
+...........................
+
+In HTML, the ``class`` attribute is used to specify a CSS class for an element. In
+ReactPy, this attribute is renamed to ``class_name`` to avoid conflicting with the
+``class`` keyword in Python. For example, the following HTML:
+
+.. code-block:: html
+
+
+
My Todo List
+
+
Build a cool new app
+
Share it with the world!
+
+
+
+Would be written in ReactPy as:
+
+.. testcode::
+
+ html.div(
+ {"class_name": "container"},
+ html.h1({"class_name": "title"}, "My Todo List"),
+ html.ul(
+ {"class_name": "list"},
+ html.li({"class_name": "item"}, "Build a cool new app"),
+ html.li({"class_name": "item"}, "Share it with the world!"),
+ ),
+ )
+
+``for`` vs ``html_for``
+.......................
+
+In HTML, the ``for`` attribute is used to specify the ``id`` of the element it's
+associated with. In ReactPy, this attribute is renamed to ``html_for`` to avoid
+conflicting with the ``for`` keyword in Python. For example, the following HTML:
+
+.. code-block:: html
+
+
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
ReactPy
-IDOM is a Python web framework for building **interactive websites without needing a
-single line of Javascript**. These sites are built from small elements of functionality
-like buttons text and images. IDOM allows you to combine these elements into reusable
-"components" that can be composed together to create complex views.
+