From 15c470e3af46f73fc189d2da9307a79d029f44f2 Mon Sep 17 00:00:00 2001 From: rmorshea Date: Sat, 20 May 2023 15:29:43 -0600 Subject: [PATCH 1/2] fix js template links --- docs/source/about/contributor-guide.rst | 7 +++---- .../guides/escape-hatches/distributing-javascript.rst | 2 +- .../source/guides/escape-hatches/javascript-components.rst | 2 +- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/about/contributor-guide.rst b/docs/source/about/contributor-guide.rst index 79cd2fb4c..e26d89e52 100644 --- a/docs/source/about/contributor-guide.rst +++ b/docs/source/about/contributor-guide.rst @@ -305,10 +305,10 @@ Other Core Repositories ReactPy depends on, or is used by several other core projects. For documentation on them you should refer to their respective documentation in the links below: -- `reactpy-react-component-cookiecutter - `__ - Template repo +- `reactpy-js-component-template + `__ - Template repo for making :ref:`Custom Javascript Components`. -- `flake8-reactpy-hooks `__ - Enforces the +- `reactpy-flake8 `__ - Enforces the :ref:`Rules of Hooks` - `reactpy-jupyter `__ - ReactPy integration for Jupyter @@ -321,7 +321,6 @@ you should refer to their respective documentation in the links below: .. ===== .. _Google Chrome: https://www.google.com/chrome/ -.. _ChromeDriver: https://chromedriver.chromium.org/downloads .. _Docker: https://docs.docker.com/get-docker/ .. _Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git .. _Git Bash: https://gitforwindows.org/ diff --git a/docs/source/guides/escape-hatches/distributing-javascript.rst b/docs/source/guides/escape-hatches/distributing-javascript.rst index a92166291..0028cee36 100644 --- a/docs/source/guides/escape-hatches/distributing-javascript.rst +++ b/docs/source/guides/escape-hatches/distributing-javascript.rst @@ -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/reactive-python/reactpy-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/javascript-components.rst b/docs/source/guides/escape-hatches/javascript-components.rst index f66ca60fb..f0a71b6b7 100644 --- a/docs/source/guides/escape-hatches/javascript-components.rst +++ b/docs/source/guides/escape-hatches/javascript-components.rst @@ -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/reactive-python/reactpy-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/ From 78f8169414a54c6f323e722571bcaafd52776b14 Mon Sep 17 00:00:00 2001 From: rmorshea Date: Tue, 23 May 2023 11:36:50 -0600 Subject: [PATCH 2/2] better HTML docs --- docs/source/_custom_js/package-lock.json | 4 +- .../html-with-reactpy/index.rst | 19 +- .../rendering-data/index.rst | 14 +- docs/source/index.rst | 1 + docs/source/reference/html-attributes.rst | 197 ++++++++++++++++++ 5 files changed, 220 insertions(+), 15 deletions(-) create mode 100644 docs/source/reference/html-attributes.rst diff --git a/docs/source/_custom_js/package-lock.json b/docs/source/_custom_js/package-lock.json index f69eb9c1c..fc00fcb83 100644 --- a/docs/source/_custom_js/package-lock.json +++ b/docs/source/_custom_js/package-lock.json @@ -19,7 +19,7 @@ } }, "../../../src/client/packages/@reactpy/client": { - "version": "0.2.1", + "version": "0.3.1", "integrity": "sha512-pIK5eNwFSHKXg7ClpASWFVKyZDYxz59MSFpVaX/OqJFkrJaAxBuhKGXNTMXmuyWOL5Iyvb/ErwwDRxQRzMNkfQ==", "license": "MIT", "dependencies": { @@ -30,7 +30,6 @@ "@types/json-pointer": "^1.0.31", "@types/react": "^17.0", "@types/react-dom": "^17.0", - "prettier": "^3.0.0-alpha.6", "typescript": "^4.9.5" }, "peerDependencies": { @@ -442,7 +441,6 @@ "@types/react-dom": "^17.0", "event-to-object": "^0.1.2", "json-pointer": "^0.6.2", - "prettier": "^3.0.0-alpha.6", "typescript": "^4.9.5" } }, diff --git a/docs/source/guides/creating-interfaces/html-with-reactpy/index.rst b/docs/source/guides/creating-interfaces/html-with-reactpy/index.rst index bdc249204..99a973d94 100644 --- a/docs/source/guides/creating-interfaces/html-with-reactpy/index.rst +++ b/docs/source/guides/creating-interfaces/html-with-reactpy/index.rst @@ -78,22 +78,20 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it Billie Holiday -In ReactPy we add these attributes to elements using keyword arguments. There are two main -notable differences though. 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 specifying ``style`` using a -string, we use a dictionary. Given this, you can rewrite the ```` element above as: +In ReactPy we add these attributes to elements using a dictionary: .. testcode:: html.img( { "src": "https://picsum.photos/id/237/500/300", + "class_name": "img-fluid", "style": {"width": "50%", "margin_left": "25%"}, "alt": "Billie Holiday", } @@ -104,10 +102,21 @@ string, we use a dictionary. Given this, you can rewrite the ```` element a Billie Holiday +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. ---------- diff --git a/docs/source/guides/creating-interfaces/rendering-data/index.rst b/docs/source/guides/creating-interfaces/rendering-data/index.rst index 29013717d..8b11ac439 100644 --- a/docs/source/guides/creating-interfaces/rendering-data/index.rst +++ b/docs/source/guides/creating-interfaces/rendering-data/index.rst @@ -80,10 +80,6 @@ With this we can now imaging writing some filtering and sorting logic using Pyth 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,6 +101,11 @@ and then ordering the elements based on the ``priority``: We could then add this code to our ``DataList`` component: +.. warning:: + + The code below produces a bunch of warnings! Be sure to tead the + :ref:`next section ` to find out why. + .. reactpy:: _examples/sorted_and_filtered_todo_list @@ -135,12 +136,11 @@ 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 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 712db3ead..8b21160f6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,6 +23,7 @@ ReactPy :caption: Reference reference/browser-events + reference/html-attributes reference/hooks-api _auto/apis reference/javascript-api diff --git a/docs/source/reference/html-attributes.rst b/docs/source/reference/html-attributes.rst new file mode 100644 index 000000000..25530b033 --- /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. + + +Noteable 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 + +
    + + +
    + +Would be written in ReactPy as: + +.. testcode:: + + html.div( + html.label({"html_for": "todo"}, "Todo:"), + html.input({"id": "todo", "type": "text"}), + ) + +``dangerously_set_inner_HTML`` +.............................. + +This is used to set the ``innerHTML`` property of an element and should be provided a +dictionary with a single key ``__html`` whose value is the HTML to be set. It should be +used with **extreme caution** as it can lead to XSS attacks if the HTML inside isn't +trusted (for example if it comes from user input). + + +All Attributes +-------------- + +`access_key `__ + A string. Specifies a keyboard shortcut for the element. Not generally recommended. + +`aria_* `__ + ARIA attributes let you specify the accessibility tree information for this element. + See ARIA attributes for a complete reference. In ReactPr, all ARIA attribute names are + exactly the same as in HTML. + +`auto_capitalize `__ + A string. Specifies whether and how the user input should be capitalized. + +`content_editable `__ + A boolean. If true, the browser lets the user edit the rendered element directly. This + is used to implement rich text input libraries like Lexical. ReactPr warns if you try + to pass children to an element with ``content_editable = True`` because ReactPy will + not be able to update its content after user edits. + +`data_* `__ + Data attributes let you attach some string data to the element, for example + data-fruit="banana". In ReactPy, they are not commonly used because you would usually + read data from props or state instead. + +`dir `__ + Either ``"ltr"`` or ``"rtl"``. Specifies the text direction of the element. + +`draggable `__ + A boolean. Specifies whether the element is draggable. Part of HTML Drag and Drop API. + +`enter_key_hint `__ + A string. Specifies which action to present for the enter key on virtual keyboards. + +`hidden