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