Merge pull request #1 from NuiCpp/feat/standalone-elements

Feat/standalone elements

Author: 5cript

docs/bundling/general.md

@@ -206,15 +206,19 @@ int main(int, char** argv)
 }
 ```
 
+:::tip
+On windows, use `app.example` as host name for custom scheme urls, because its excluded from the DNS resolver, avoiding a 2 second delay.
+:::
+
 In the frontend you can then use the custom scheme:
 ```css
 .foo {
-  background: url(nui://any_virtual_host_here/background.png);
+  background: url(nui://app.example/background.png);
 }
 ```
 
 ```javascript
-import EditorWorker from 'url:nui://host/monaco-editor/esm/vs/editor/editor.worker.js';
+import EditorWorker from 'url:nui://app.example/monaco-editor/esm/vs/editor/editor.worker.js';
 ```
 
 ### Virtual Host Name to Folder Mapping

docs/reference/standalone_element.md

@@ -0,0 +1,31 @@
+# Standalone Element
+
+A standalone element is an element that is not part of the Nui::Dom.
+These elements can be used to pass them to javascript libraries expecting HTML elements.
+
+```cpp
+#include <nui/frontend/elements.hpp>
+#include <nui/frontend/attributes.hpp>
+#include <nui/frontend/dom/element.hpp>
+
+struct MyComponent::Implementation
+{
+    std::shared_ptr<Nui::Dom::Element> element{};
+};
+
+Nui::ElementRenderer MyComponent::render()
+{
+    using namespace Nui::Elements;
+    using namespace Nui::Attributes;
+
+    return div{
+        id = "my-component",
+        !reference.onMaterialize([this](Nui::val const& element){
+            // Create a standalone element
+            impl_->element = Nui::Dom::makeStandaloneElement(div{}("Hello World!"));
+
+            Nui::val::global("assignElementToJavascriptFramework")(element->val());
+        })
+    }();
+}
+```

docs/tutorials/attributes.md

@@ -248,4 +248,20 @@ const auto ui = input{
     // will not be set at all if maybeAString is nullopt:
     value = maybeAString
 };
-```
+```
+
+## Delayed Attributes
+Sometimes you want to set an attribute after the element is inserted into the DOM.
+This can be done with the exclamation mark:
+```cpp
+using namespace Nui::Elements;
+using namespace Nui::Attributes;
+using Nui::Elements::div;
+
+const auto d = div{
+    !reference = [](Nui::val elem){
+        // elem satisfies isConnected here https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected
+    }
+}();
+```
+

docs/tutorials/observed_rendering.md

@@ -12,11 +12,36 @@ Nui::Observed<int> number{0};
 
 const auto ui = div{}(
     observe(str, number),
-    // This function is recalled and regenerates its respective elements, 
+    // This function is recalled and regenerates its respective elements,
     // when 'str' or 'number' changes.
-    [&str, &number](){
+    [&str, &number]() -> Nui::ElementRenderer {
         const auto result = *str + std::to_string(*number);
         return span{}(result);
     }
 )
+```
+
+## shared_ptr of Observed
+
+Sometimes Observed may expire while the element affected by it is still part of the DOM.
+Nui can use weak_ptrs to avoid dangling pointers to expired Observed.
+```cpp
+#include <nui/frontend.hpp>
+
+/*...*/
+
+std::shared_ptr<Nui::Observed<std::string>> str = std::make_shared<Nui::Observed<std::string>>("test");
+
+const auto ui = div{}(
+    observe(str),
+    // This function is recalled and regenerates its respective elements,
+    // when 'str' changes. Unless str is expired.
+    [weak = std::weak_ptr{str}]() -> Nui::ElementRenderer {
+        if (auto str = weak.lock(); str)
+        {
+            return span{}(str->value());
+        }
+        return Nui::nil();
+    }
+)
 ```

docs/tutorials/range_rendering.md

@@ -63,6 +63,16 @@ auto foo() {
                 std::transform(proxy->begin(), proxy->end(), proxy->begin(), [](int elem){
                     return elem * 2;
                 });
+
+                // You can also work directly on the value and call modify later:
+                auto& value = numbers.value();
+                std::transform(value.begin(), value.end(), value.begin(), [](int elem){
+                    return elem * 2;
+                });
+
+                // modifyNow also calls the eventContext executeActiveEventsImmendiately.
+                // This is not necessary from event attributes, because its called at the end anyway.
+                numbers.modifyNow();
             }
         }()
     );
@@ -122,4 +132,16 @@ auto foo() {
         }
     )
 }
-```
+```
+
+## Notes about the Optimization
+The ranges optimization that is applied to Observed<std::vector> and Observed<std::deque> makes it so that only the changed/inserted elements are rerendered and only erased elements are removed and nothing else is rerendered.
+This is done by tracking the changes using some algorithms on an interval tree.
+
+Insertions, modifications and erasures are only ever tracked alone, so if you switch from inserting elements to modifying elements a rerender is forced.
+If you erase something after modifying, all erased elements that were previously modified will not be rerendered only if the erasure happens at the end.
+If you erase something after inserting, all erased elements that were previously inserted will not be rerendered only if the erasure happens at the end.
+
+All wisdoms about modifying a vector apply to these optimizations. It is optimal to only ever add or erase from the end of the vector.
+The most detrimental thing you can do is inserting at every odd position or erasing at every odd position, this will defeat the optimization and it will
+be much better to just rerender the entire range.

sidebars.js

@@ -210,6 +210,11 @@ const sidebars = {
                     type: 'doc',
                     id: 'reference/text',
                     label: 'Plain Text Nodes',
+                },
+                {
+                    type: 'doc',
+                    id: 'reference/standalone_element',
+                    label: 'Standalone Element',
                 }
             ]
         },