docs: document better how to use classical ipywidgets in components

We also give specific examples for ipyaggrid and ipydatagrid which
are quite popular with solara.

Based on discussion on discord and:
 #512
 #511

solara/website/pages/documentation/advanced/content/10-howto/50-ipywidget_libraries.md

@@ -26,7 +26,7 @@ marker = Marker(location=(52.1, 10.1), draggable=True)
 m.add_layer(marker)
 ```
 
-In Solara, we should not create widgets, but elements instead. We can create elements using the `.element(...)` method. This method takes the same arguments as the widget constructor, but returns an element instead of a widget. The element can be used in the same way as a widget, but it is not a widget. It is a special object that can be used in Solara.
+In Solara, ideally, we should not create widgets, but elements instead. We can create elements using the `.element(...)` method. This method takes the same arguments as the widget constructor, but returns an element instead of a widget. The element can be used in the same way as a widget, but it is not a widget. It is a special object that can be used in Solara.
 
 However, how do we add the marker to the map? The map element object does not have an `add_layer` method. That is the downside of using the React-like API of Solara. We cannot call methods on the widget
 anymore. Instead, we need to pass the marker to the layers argument. That, however, introduces a new problem. Ipyleaflet by default adds a layer to the map when it is created, and the `add_layer` adds the second layer. We now need to manually add the map layer ourselves.
@@ -87,6 +87,220 @@ def Page():
 
 ```
 
+## Escape hatch
+
+Some libraries do not give access to the widget classes, or wrap the creation of widgets into a function making it impossible to create an element.
+
+### Quick and bad way
+
+If you quickly want to show a widget in your prototype, and want to avoid all the boilerplate at the
+cost of a bit of a memory leak, use the following technique.
+
+Here we directly create a widget in the render function instead of indirectly via an element.
+Since only elements get automatically added to its parent component, so we need to manually
+call [display](/api/display).
+
+```solara
+import solara
+import ipywidgets as widgets
+
+
+@solara.component
+def Page():
+    button_widget = widgets.Button(description="Classic Widget")
+    solara.display(button_widget)
+
+    def change_description(btn):
+        button_widget.description = "Great escape hatch"
+    button_widget.on_click(change_description)
+```
+
+With this approach, there are two issues. First, we do not clean up the widget we created by calling `.close()` on it. Although
+we can do that in the cleanup function of a [use_effect](/api/use_effect), in some situations the render function can be called,
+without calling the use_effect.
+
+The second issue is that every time to component gets rerendered (argument change, or state changes
+like a reactive variable it depends on) it will re-create the widget.
+
+This last issue is demonstrated in this example. We modify the above example by adding an extra state change (modifying the
+`if_i_change_we_recreate_the_widget` reactive variable) that causes the button to be completely re-created, resetting the description.
+
+```solara
+import solara
+import ipywidgets as widgets
+
+
+@solara.component
+def Page():
+    if_i_change_we_recreate_the_widget = solara.use_reactive(0)
+    print("if_i_change_we_recreate_the_widget", if_i_change_we_recreate_the_widget.value)
+
+    button_widget = widgets.Button(description="Classic Widget")
+    solara.display(button_widget)
+
+
+    def change_description(btn):
+        # this 'works'
+        button_widget.description = "Great escape hatch"
+        # but because this will trigger a re-render, it will
+        # re-create the widget
+        if_i_change_we_recreate_the_widget.value += 1
+    # Now we can call normal functions on it
+    button_widget.on_click(change_description)
+```
+
+### Proper way
+
+If you want to have more control on when your widgets gets created (only once for instance), and how to clean it up, uou can use the the following general pattern,
+here demonstrated using an ipywidget Button:
+
+```solara
+import solara
+import ipywidgets as widgets
+
+
+@solara.component
+def Page():
+    if_i_change_we_rerender = solara.use_reactive(0)
+    # Important to use a widget component, not a function component,
+    # otherwise the children will be reset after we change it in the
+    # use_effect function.
+    container = solara.v.Html(tag="div")
+    # Because of this, this container will not work:
+    # container = solara.Column()
+
+    def add_classic_widget():
+        # generate your normal widget
+        button_widget = widgets.Button(description="Classic Widget")
+
+        def change_description(btn):
+            button_widget.description = "Proper escape hatch"
+            # This will trigger a rerender, but not re-execute the use_effect
+            if_i_change_we_rerender.value += 1
+        # Now we can call normal functions on it
+        button_widget.on_click(change_description)
+
+        # add it to the generated widget by solara/reacton
+        container_widget = solara.get_widget(container)
+        container_widget.children = (button_widget,)
+
+        def optional_cleanup():
+            # ideally, we cleanup the widgets we created.
+            # If you skip this step, the widgets will be garbage collected
+            # when the solara virtual kernel gets closed.
+            # In the Notebook or Voila skipping this step can cause a (small)
+            # memory leak.
+            container_widget.children = ()
+            button_widget.on_click(change_description, remove=True)
+            button_widget.layout.close()
+            button_widget.style.close()
+            button_widget.close()
+        return optional_cleanup
+
+    solara.use_effect(add_classic_widget, dependencies=[])
+
+    # We could potentially update the button based on if_i_change_we_rerender using:
+    # solara.use_effect(update_button, dependencies[if_i_change_we_rerender.value])
+    # However, getting a reference to the widget is a bit trickier, use solara.use_ref
+    # https://reacton.solara.dev/en/latest/api/#use_ref would come handy, e.g.
+    # button = solara.use_ref(None)
+    # And assign button.current in the add_classic_widget function and access
+    # if in other use_effects
+    return container
+```
+
+
+
+## ipyaggrid
+
+[IPyAgGrid](https://github.com/widgetti/ipyaggrid) has the disadvantage that the constructor arguments
+are not the same as the traits or property names on the object. For instance, when calling the
+Grid constructor, `grid_data` is used, while updating the dataframe goes via [`.update_grid_data(...)`](https://widgetti.github.io/ipyaggrid/guide/create.html#update-data)
+
+
+```python
+import ipyaggrid
+grid = ipyaggrid.Grid(grid_data=df)
+...
+grid.update_grid_data(df_other)
+```
+
+When using solara/reacton components, we do not create widgets directly, but prefer to use elements (descriptions of component instances)
+to get lifetime management, and automatic updates of traits. This automatic updating of traits however, does not work in this case,
+since it should call `.update_grid_data(...)` instead.
+
+To get around this, we can again use `use_effect` whenever the dataframe (or other state that signals a change in the dataframe) changes.
+
+```solara
+from typing import cast
+import ipyaggrid
+import plotly.express as px
+import solara
+
+
+df = px.data.iris()
+species = solara.reactive("setosa")
+
+
+@solara.component
+def Page():
+    df_filtered = df.query(f"species == {species.value!r}")
+    solara.Select("Filter species", value=species, values=["setosa", "versicolor", "virginica"])
+
+    # does NOT update aggrid when grid_data argument changes
+    # since grid_data is not a trait, so letting reacton/solara update this property has no effect
+    grid = ipyaggrid.Grid.element(grid_data=df_filtered)
+
+    # Instead, we need to get a reference to the widget and call .update_grid_data in a use_effect
+    def update_df():
+        # NOTE: the cast is optional, and only needed if you like type hinting
+        grid_widget = cast(ipyaggrid.Grid, solara.get_widget(grid))
+        grid_widget.update_grid_data(df_filtered)
+
+    # Note, instead of having df_filtered as a dependency, we use species which is easier/cheaper
+    # to compare.
+    solara.use_effect(update_df, [species.value])
+```
+
+[Or check out our more worked out example](https://solara.dev/examples/libraries/ipyaggrid).
+
+
+## ipydatagrid
+
+The problem with ipydatagrid is similar to aggrid, except here we need to use the `dataframe` argument for the
+constructor, and the `.data` property for updating the dataframe.
+
+```solara
+from typing import Dict, List, cast
+import ipydatagrid
+import plotly.express as px
+import solara
+
+
+df = px.data.iris()
+species = solara.reactive("setosa")
+
+
+@solara.component
+def Page():
+    df_filtered = df.query(f"species == {species.value!r}")
+    solara.Select("Filter species", value=species, values=["setosa", "versicolor", "virginica"])
+    datagrid = ipydatagrid.DataGrid.element(dataframe=df, selection_mode="row")
+
+    # we need to use .data instead (on the widget) to update the dataframe
+    # similar to aggrid
+    def update_df():
+        # NOTE: the cast is optional, and only needed if you like type hinting
+        datagrid_widget = cast(ipydatagrid.DataGrid, solara.get_widget(datagrid))
+        # Updating the dataframe goes via the .data property
+        datagrid_widget.data = df
+
+    solara.use_effect(update_df, [species.value])
+```
+
+[Or check out our more worked out example](https://solara.dev/examples/libraries/ipydatagrid).
+
+
 ## Wrapper libraries
 
 However, because we care about type safety, we generate wrapper components for some libraries. This enables type completion in VSCode, type checks with VSCode, and mypy.

solara/website/pages/documentation/examples/libraries/ipyaggrid.py

@@ -0,0 +1,57 @@
+"""
+# ipyaggrid
+
+[IPyAgGrid](https://github.com/widgetti/ipyaggrid) is a Jupyter widget for the [AG-Grid](https://www.ag-grid.com/) JavaScript library.
+
+It is a feature-rich datagrid designed for enterprise applications.
+
+To use it in a Solara component, requires a bit of manual wiring up of the dataframe and grid_options, as the widget does not have traits for these.
+
+For more details, see [the IPywidget libraries Howto](https://solara.dev/docs/howto/ipywidget-libraries).
+
+
+"""
+from typing import cast
+
+import ipyaggrid
+import plotly.express as px
+
+import solara
+
+df = px.data.iris()
+species = solara.reactive("setosa")
+filter_species = solara.reactive(True)
+
+
+@solara.component
+def AgGrid(df, grid_options):
+    """Convenient component wrapper around ipyaggrid.Grid"""
+
+    def update_df():
+        widget = cast(ipyaggrid.Grid, solara.get_widget(el))
+        widget.grid_options = grid_options
+        widget.update_grid_data(df)  # this also updates the grid_options
+
+    # when df changes, grid_data will be update, however, ...
+    el = ipyaggrid.Grid.element(grid_data=df, grid_options=grid_options)
+    # grid_data and grid_options are not traits, so letting them update by reacton/solara has no effect
+    # instead, we need to get a reference to the widget and call .update_grid_data in a use_effect
+    solara.use_effect(update_df, [df, grid_options])
+    return el
+
+
+@solara.component
+def Page():
+
+    grid_options = {
+        "columnDefs": [
+            {"headerName": "Sepal Length", "field": "sepal_length"},
+            {"headerName": "Species", "field": "species"},
+        ]
+    }
+
+    df_filtered = df.query(f"species == {species.value!r}") if filter_species.value else df
+
+    solara.Select("Filter species", value=species, values=["setosa", "versicolor", "virginica"])
+    solara.Checkbox(label="Filter species", value=filter_species)
+    AgGrid(df=df_filtered, grid_options=grid_options)

solara/website/pages/documentation/examples/libraries/ipydatagrid.py

@@ -0,0 +1,54 @@
+"""
+# ipydatagrid
+
+[ipydatagrid](https://github.com/bloomberg/ipydatagrid) is a Jupyter widget developed by Bloomberg which describes itself as a
+"Fast Datagrid widget for the Jupyter Notebook and JupyterLab".
+
+To use it in a Solara component requires a bit of manual wiring up of the dataframe, as this widget does not use a trait for this
+(and the property name does not match the constructor argument).
+
+For more details, see [the IPywidget libraries Howto](https://solara.dev/docs/howto/ipywidget-libraries).
+
+
+"""
+from typing import Dict, List, cast
+
+import ipydatagrid
+import plotly.express as px
+
+import solara
+
+df = px.data.iris()
+species = solara.reactive("setosa")
+filter_species = solara.reactive(True)
+
+
+@solara.component
+def DataGrid(df, **kwargs):
+    """Convenient component wrapper around ipydatagrid.DataGrid"""
+
+    def update_df():
+        widget = cast(ipydatagrid.DataGrid, solara.get_widget(el))
+        # This is needed to update the dataframe, see
+        #  https://solara.dev/docs/howto/ipywidget-libraries for details
+        widget.data = df
+
+    el = ipydatagrid.DataGrid.element(dataframe=df, **kwargs)  # does NOT change when df changes
+    # we need to use .data instead (on the widget) to update the dataframe
+    solara.use_effect(update_df, [df])
+    return el
+
+
+@solara.component
+def Page():
+    selections: solara.Reactive[List[Dict]] = solara.use_reactive([])
+    df_filtered = df.query(f"species == {species.value!r}") if filter_species.value else df
+
+    with solara.Card("ipydatagrid demo", style={"width": "700px"}):
+        solara.Select("Filter species", value=species, values=["setosa", "versicolor", "virginica"])
+        solara.Checkbox(label="Filter species", value=filter_species)
+        DataGrid(df=df_filtered, selection_mode="row", selections=selections.value, on_selections=selections.set)
+        if selections.value:
+            with solara.Column():
+                solara.Text(f"Selected rows: {selections.value!r}")
+                solara.Button("Clear selections", on_click=lambda: selections.set([]))