solara-ui 1.45.0__py3-none-any.whl

solara/website/pages/documentation/advanced/content/20-understanding/17-rules-of-hooks.md

@@ -0,0 +1,192 @@
+---
+title: The rules of hooks in Solara
+description: Learn the rules that govern the usage of hooks in your Solara application.
+----
+# Rules of hooks
+
+Hooks are Python function whose name start with `use_`. The most used hook is [use_state](https://solara.dev/documentation/api/hooks/use_state) which is used to manage the state of a component.
+
+Hooks can only be called at the top level of a function component or a custom hook. They cannot be called inside loops, conditions, or nested functions.
+The reason for this is that hooks rely on the order in which they are called to maintain state between renders. If a hook is called conditionally, it may not be called on every render, which can mix up the states.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    x, set_x = solara.use_state(1)  # state 'slot' 1
+    if x < 10:
+        y, set_y = solara.use_state(2)  # state 'slot' 2
+    else:
+        y, set_y = solara.use_state("foo") # *also* state 'slot' 2
+    solara.Text("Done")
+```
+
+In the above example, the `use_state(2)` and `use_state("foo")` is called conditionally, which means that the state 'slot' 2 (meaning, `y` and `set_y`) sometimes refer to the integer `2` and sometimes to the string `"foo"`. This gives unexpected behavior and will lead to bugs.
+
+
+The rules of hooks are checked by Solara, if you break the rules, you will get a warning, and in the future (Solara v2.0) you will get an error (an exception is raised).
+
+## Example
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(10):
+        solara.use_state(1)
+    solara.Text("Done")
+```
+
+Will give the warning:
+```
+/some/prefix/site-packages/solara/solara/validate_hooks.py:122: UserWarning: /my/app.py:56: Page: `use_state` found within a loop created on line 55
+To suppress this check, replace the line with:
+                solara.use_state(1)  # noqa: SH103
+
+Make sure you understand the consequences of this, by reading about the rules of hooks at:
+    https://solara.dev/documentation/advanced/understanding/rules-of-hooks
+```
+
+As the warning suggests, you can suppress the warning by adding `# noqa: SH103` to the line that breaks the rules.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(10):
+        solara.use_state(1)  # noqa: SH103
+
+    solara.Text("Done")
+```
+
+The warning can also be suppressed for the whole component by adding `# noqa: SH103` to the function definition.
+
+```python
+import solara
+
+
+@solara.component
+def Page():  # noqa: SH103
+    for i in range(10):
+        solara.use_state(1)
+
+    solara.Text("Done")
+```
+
+
+However, we strongly advise against this, and you should only use it if you know what you are doing (knowing the the loop will always run a fixed amount of times).
+
+If you want to have an error raised instead of a warning, you can set the environment variable `SOLARA_CHECK_HOOKS=raise`, this is
+planned to be the default in Solara v2.0.
+
+In that case, you should get an error like this:
+
+```
+
+solara.validate_hooks.HookValidationError: /my/app.py:56: Page: `use_state` found within a loop created on line 55
+To suppress this check, replace the line with:
+                solara.use_state(1)  # noqa: SH103
+
+Make sure you understand the consequences of this, by reading about the rules of hooks at:
+    https://solara.dev/documentation/advanced/understanding/rules-of-hooks
+```
+
+
+For convenience, you can also disable the check by setting the environment variable `SOLARA_CHECK_HOOKS=off`, but we strongly advise against this.
+
+## Types of error
+
+### Early return (SH101)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+     solara.Text("Done")
+    if x < 10:
+        return  # will cause the below use_state to not always be called
+    solara.use_state(1)
+```
+
+### Conditional use (SH102)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    if x < 10:
+        solara.use_state(1)  # will cause the use_state to not always be called
+    solara.Text("Done")
+```
+
+
+### Loop use (SH103)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    for i in range(x):
+        solara.use_state(1)  # will cause the use_state to not always be a constant number of times
+    solara.Text("Done")
+```
+
+### Nested function use (SH104)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    def inner():
+        solara.use_state(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    inner()
+    solara.Text("Done")
+```
+
+
+### Variable assignment (SH105)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    x = solara.use_state
+    x(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    solara.Text("Done")
+```
+
+
+### Exception use (SH106)
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    try:
+        this_might_fail()
+        solara.use_state(1)  # will use_state always be called? Difficult to analyze, so don't do it
+    except:
+        pass
+    solara.Text("Done")
+```
+
+For this reason, it's also advised to always call hooks first, before doing anything else in a function component that might raise
+an exception.

solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md

@@ -0,0 +1,166 @@
+---
+title: Using Solara with containers to build complex UIs
+description: Solara allows for using python with statements to populate your UIs in a structured manner. This makes it easy to compose different components to build cohesive
+    wholes.
+---
+
+# Laying out components with containers
+
+## Introduction
+Some components, such as our favorite `ClickButton` only add logic on top of an existing component:
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    # We return a single component
+    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+
+Page = ClickButton
+```
+
+
+## Containers with children
+However, more sophisticated components will add multiple components together into a container component, let's take a look at an example.
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    button_increase = solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+    button_reset = solara.Button(label="Reset", on_click=reset_count)
+
+    return solara.Row(children=[button_increase,
+                                 button_reset,
+                                 ])
+
+
+Page = FancyClickButton
+
+```
+
+
+Here we use an [HBox](/documentation/components/layout/hbox) to lay out two child components horizontally.
+
+
+## Cleaner way to add children to containers
+
+Because using container components is so common, we created a more convenient way to pass children to components and made your code look neater and more structured as well (avoiding nested lists).
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    with solara.Row() as main:
+        solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+        solara.Button(label="Reset", on_click=reset_count)
+    return main
+
+Page = FancyClickButton
+
+```
+
+Here we are using the top-level Row as a context manager (with the name `main`). All child elements created within this context are automatically added as a child.
+
+### About Context managers
+
+Context managers are a Python language feature, there are two ways to use them:
+
+```python
+
+with some_anonymous_context_manager():
+    print("some code")
+
+with some_named_context_manager() as this_is_my_name:
+    print("some other code")
+```
+
+Where the last example assigns the context manager to a variable. In Solara we only need to do that to the top context manager, since we need to return that in our [render function](/documentation/advanced/understanding/anatomy).
+
+All Reacton or Solara components return elements that can be used as context managers. Context managers allow for code to be executed before and after your code block inside of the context manager. This allows us to capture all elements created inside of the context manager. If you want to know more about context managers, consult the Python documentation since this is not Solara specific.
+
+
+### Nested layout
+
+Adding children using context managers work at any level, you can nest Rows and Columns [or any other containers](/api#components).
+
+
+```solara
+import solara
+
+
+@solara.component
+def FancyClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def increase_count():
+        set_clicks(clicks + 1)
+
+    def reset_count():
+        set_clicks(0)
+
+    with solara.Column() as main:
+        with solara.Row():
+            solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
+            solara.Button(label="Reset", on_click=reset_count)
+        solara.Text("I am a child of a VBox")
+    return main
+
+Page = FancyClickButton
+
+```
+
+
+## Automatic containers
+
+
+Instead of returning the main container, Solara also allows you to not have a return value (or return `None`).
+If that is the case, Solara will look at what elements you created. If you created one, that element will be taken
+as a return value instead. If you make more than one element, those elements will be automatically wrapped by
+a [Column](/documentation/components/layout/column). The only benefit of returning an element, is that we can infer the correct return type,
+which can be useful for testing purposes. Users should probably never return an element, but use the automatic
+container feature.
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+    solara.Button(label=f"Reset", on_click=lambda: set_clicks(0))
+
+Page = ClickButton
+```

solara/website/pages/documentation/advanced/content/20-understanding/20-solara.md

@@ -0,0 +1,18 @@
+---
+title: Understanding different parts of Solara
+description: Solara is made of two main components, the bulk of the Solara package with UI elements that can be used together with Jupyter, and Solara server, which
+    allows for these UI elements to be used in standalone apps and dashboards
+---
+# Solara
+
+Solara combines [ipywidgets](./ipywidgets), [reacton](./reacton) and puts it into a opinionated framework to make web apps with a focus on data (data apps for short).
+
+Solara consists of two main parts
+
+## Solara-ui
+
+A set of opinionated react components and hooks that allow you to build web apps and data apps faster.
+
+## Solara-server
+
+A web framework for deploying web apps or data apps in production. Opinionated about pages and routing.

solara/website/pages/documentation/advanced/content/20-understanding/40-routing.md

@@ -0,0 +1,256 @@
+---
+title: Understanding routing in multi-page solara apps
+description: Dive into Solara's routing, which provides a powerful way to compose multiple pages or dashboards into an integrated app.
+---
+# Routing
+
+Routing takes care of linking a web address (more specifically the [pathname](https://developer.mozilla.org/en-US/docs/Web/API/Location), e.g. "/docs/basics/solara") to a state of the UI,
+usually in the form of what appears as pages to a user.
+
+
+Routing includes navigation (hitting the back and forward button of your browser) without causing a page reload.
+
+
+## Automatic routing
+
+Setting up routing can be repetitive, and therefore Solara comes also with a more opinionated method for setting up routing automatically.
+
+### Based on a directory
+
+Using [`generate_routes_directory(path: Path) -> List[solara.Route]:`](/documentation/api/routing/generate_routes_directory) we can request Solara to give us a list of
+routes by scanning a directory for Python scripts, Notebooks and Markdown files.
+
+This function is being used by Solara if you run solara server with a directory as argument name, as used in [our Multi Page guide](/documentation/advanced/howto/multipage). More details can be found there.
+
+
+### Based on a Python package
+
+Similar to the previous section [`generate_routes(module: ModuleType) -> List[solara.Route]:`](/documentation/api/routing/generate_routes) will return a list of routes by scanning a Python package or module for `Page` components, or `app` elements. Again, more information can be found at [our Multi Page guide](/documentation/advanced/howto/multipage).
+
+## Manually defining routes
+
+In Solara, we set up routing by defining a list of `solara.Route` objects, where each route can have another list of routes, its children, forming
+a tree of routes. We assign this list to the `routes` variable in your main app script or module.
+
+### Defining route components
+
+If no `Page` component is found in your main script or module, Solara will assume you have either set the `component` or the `module` argument of the `solara.Route` object.
+
+For example
+
+```python
+import solara
+from solara.website.pages.examples.utilities import calculator
+
+
+@solara.component
+def Home():
+    solara.Markdown("Home")
+
+
+@solara.component
+def About():
+    solara.Markdown("About")
+
+
+routes = [
+    solara.Route(path="/", component=Home, label="Home"),
+    # the calculator module should have a Page component
+    solara.Route(path="calculator", module=calculator, label="Calculator"),
+    solara.Route(path="about", component=About, label="About"),
+]
+```
+
+### Defining route components
+
+If you do define a `Page` component, you are fully responsible for how routing is done, but we recommend using [use_route](/documentation/api/routing/use_route).
+
+An example route definition could be something like this:
+
+```python
+import solara
+
+routes = [
+    # route level == 0
+    solara.Route(path="/"),  # matches empty path ''
+    solara.Route(
+        # route level == 1
+        path="docs",  # matches '/docs'
+        children=[
+            # route level == 2
+            solara.Route(path="basics", children=[  # matches '/docs/basics'
+                # route level == 3
+                solara.Route(path="react"),      # matches '/docs/basics/react'
+                solara.Route(path="ipywidgets"), # matches '/docs/basics/ipywidgets'
+                solara.Route(path="solara"),     # matches '/docs/basics/solara'
+            ]),
+            solara.Route(path="advanced")  # matches '/docs/advanced'
+        ],
+    ),
+    solara.Route(
+        path="blog",
+        # route level == 1
+        children=[
+            solara.Route(path="/"),   # matches '/blog'
+            solara.Route(path="foo"), # matches '/blog/foo'
+            solara.Route(path="bar"), # matches '/blog/bar'
+        ],
+    ),
+    solara.Route(path="contact")  # matches '/contact'
+]
+
+# Lets assume our pathname is `/docs/basics/react`,
+@solara.component
+def Page():
+    level = solara.use_route_level()  # returns 0
+    route_current, routes_current_level = solara.use_route()
+    # route_current is routes[1], i.e. solara.Route(path="docs", children=[...])
+    # routes_current_level is [routes[0], routes[1], routes[2], routes[3]], i.e.:
+    #    [solara.Route(path="/"), solara.Route(path="docs", children=[...]),
+    #     solara.Route(path="blog", children=[...]), solara.Route(path="contact")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some top level navigation here based on route_current_level and route_current
+        return MyFirstLevelChildComponent()
+```
+
+Routes are matched by splitting the pathname around the slash ("/") and matching each part to the routes. The level of the depth into the tree is what we call the `route_level`, which starts at 0, the top level.
+Each call to `use_route` will return the current route (if there is a match to the current path) and the list of siblings including itself.
+
+
+Now the `MyFirstLevelChildComponent` component is responsible for rendering the second level navigation:
+
+```python
+@solara.component
+def MyFirstLevelChildComponent():
+    level = solara.use_route_level()  # returns 1
+    route_current, routes_current_level = solara.use_route()
+    # route_current is routes[1].children[0], i.e. solara.Route(path="basics", children=[...])
+    # routes_current_level is [routes[1].children[0], routes[1].children[1]], i.e.:
+    #    [solara.Route(path="basics", children=[...]), solara.Route(path="advanced")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some mid level navigation here based on route_current_level and route_current
+        return MySecondLevelChildComponent()
+
+```
+
+And the `MySecondLevelChildComponent` component is responsible for rendering the third level navigation:
+
+```python
+@solara.component
+def MySecondLevelChildComponent():
+    level = solara.use_route_level()  # returns 2
+    route_current, routes_current_level = solara.use_route()
+    # route_current is routes[1].children[0].children[0], i.e. solara.Route(path="react")
+    # routes_current_level is [routes[1].children[0].children[0], routes[1].children[0].children[1], routes[1].children[0].children[2]], i.e.
+    #    [solara.Route(path="react"), solara.Route(path="ipywidgets"), solara.Route(path="solara")]
+    if route_current is None: # no matching route
+        return solara.Error("oops, page not found")
+    else:
+        # we could render some mid level navigation here based on route_current_level and route_current
+        if route_current.path == "react":
+            return DocsBasicReact()  # render the actual content
+        elif route_current.path == "ipywidgets":
+            return DocsBasicIpyWidgets()
+        elif route_current.path == "solara":
+            return DocsBasicSolara()
+        else:
+            return solara.Error("oops, not possible!")
+
+```
+
+From this code, we can see we are free how we transform the routes into the state of the UI (i.e. which components are rendered).
+
+## Adding data
+
+Often, your render logic needs some extra data on what to display. For instance, you may want to dynamically render tabs based on the routes,
+which requires you to have a label, and know which component to add.
+For this purposed we added `label: str` and the `component' attributes, so you can defines routes likes:
+
+```python
+routes = [
+    solara.Route("/", component=Home, label="What is Solara ☀️?"),
+    solara.Route("docs", component=docs.App, label="Docs", children=docs.routes),
+    solara.Route(
+        "demo",
+        component=demo.Demo,
+        children=demo.routes,
+        label="Demo",
+    ),
+    ...
+]
+```
+
+In the case where you did not specify a `Page` component, label is used for the [Title](/documentation/components/page/title) component.
+
+If you need to store more data in the route, you are free to put whatever you want in the `data` attribute, see also [Route](/documentation/api/routing/route).
+
+
+
+## Linking
+
+Note that all routes are relative, since a component does not know if it is embedded into a larger application, which may also do routing.
+
+
+Therefore you should never use the `route.path` for navigation since the route object has no knowledge of the full url
+(e.g. `/docs/basics/ipywidgets`) but only knows its small piece of the pathname (e.g. `ipywidgets`)
+
+Using [`resolve_path`](/documentation/api/routing/resolve_path) we can request the full url for navigation.
+
+```python
+def resolve_path(path_or_route: Union[str, solara.Route], level=0) -> str:
+    ...
+```
+
+We can pass this full URL to the [`solara.Link`](/documentation/components/advanced/link) component, e.g. like:
+
+```python
+@solara.component
+def LinkToIpywidgets():
+    route_ipywidgets = routes.children[1].children[0].children[1]
+    # route_ipywidgets.path == "ipywidgets"
+    path = solara.resolve_path(route_ipywidgets)
+    # path == '/docs/basics/ipywidgets
+    with solara.Link(path) as main:
+        solara.Button("read about ipywidgets")
+    return main
+```
+
+### Linking to Sections of a Page
+
+The `solara.Link` component also supports linking to HTML elements identified by id. Although most Solara components don't directly support the id attribute, you can assign ids to all ipyvuetify components, using the `attributes` argument:
+
+```python
+solara.v.Btn(attributes={"id": "my-id"}, ...)
+```
+
+You can then link to a particular element by appending `#` followed by its id to your link, i.e. `solara.Link(route_or_path="/page#my-id")`. If you want the page to smoothly scroll to the linked element, you should give an element that contains it (for instance the `html`-element) the following CSS rule:
+
+```css
+html {
+    scroll-behaviour: smooth;
+}
+```
+
+## Fully manual routing
+
+If you want to do routing fully manually, you can use the [`solara.use_router`](/documentation/api/routing/use_router) hook, and use the `.path` attribute.
+
+```python
+import solara
+
+
+@solara.component
+def Page():
+    router = solara.use_router()
+    path = router.path
+    parts = path.split("/")
+    solara.Markdown(f"Path = {path!r}, and split up into {parts!r}")
+    # now you can do anything with path or parts.
+    # e.g.
+    # if parts[0] == "docs":
+    #   solara.Markdown("You are in the docs section")
+```