solara-ui 1.45.0__py3-none-any.whl

solara/website/pages/documentation/advanced/content/15-reference/40-static_files.md

@@ -0,0 +1,31 @@
+---
+title: Using static files and resources in your Solara application
+description: When using Solara, you can host static files, like images, which will then be available at /static/public, in the ../public folder.
+---
+# Static files
+
+Files located on your local filesystem at the `../public` directory will be served by the Solara server at `/static/public`. A typical directory layout looks like this:
+
+```
+├── pages
+│   ├── 01-landing-page.md
+│   ├── 02-some_app.py
+└── public
+    └── beach.jpeg
+```
+
+For instance, on this server, the `beach.jpeg` file will be available at `/static/public/beach.jpeg` and the full URL will be [`https://solara.dev/static/public/beach.jpeg`](https://solara.dev/static/public/beach.jpeg)
+
+Putting the `public` directory 1 level higher than the `pages` directory avoids name collision with pages.
+
+```solara
+import solara
+
+
+@solara.component
+def Page():
+    image_url = "/static/public/beach.jpeg"
+    with solara.Card(title="The following image is served from the ../public directory"):
+        solara.Image(image_url)
+
+```

solara/website/pages/documentation/advanced/content/15-reference/41-asset-files.md

@@ -0,0 +1,72 @@
+---
+title: Incorporating your assets, styles, and logos into your app
+description: Solara looks for overrides of certain style and asset files in the assets folder by default. You can use these to incorporate your branding into your dashboard or app.
+---
+# Assets files
+
+Asset files are special files with are loaded by Solara-server and thus have a special meaning, and come with defaults. Current supported assets files are:
+
+ * `favicon.png` and/or `favicon.svg` - Image shown by the browser (usually in the tab). If SVG is not provided, default `favicon.svg` of the solara server may override your custom favicon.png depending on the browser. Providing both PNG and SVG versions is recommended.
+ * `style.css` - Default `CSS` used by Solara.
+ * `custom.css` - Custom `CSS` you can override for your project (empty `CSS` file by default).
+ * `custom.js` - Custom Javascript you can use for your project (empty Javascript file by default).
+ * `theme.js` - Javascript file containing the definitions for [vuetify themes](https://v2.vuetifyjs.com/en/features/theme/) ([example theme.js file](https://github.com/widgetti/solara/blob/master/solara/website/assets/theme.js)).
+
+
+Assets files can be overridden by putting a file in the `../assets` directory.  A typical directory layout looks like this:
+
+```
+├── pages
+│   ├── 01-landing-page.md
+│   ├── 02-some_app.py
+└── public
+    └── beach.jpeg
+└── assets
+    ├── custom.css
+    ├── custom.js
+    ├── theme.js
+    └── favicon.png
+```
+
+All assets files are served under `/static/assets/<filename>`, but how the assets go to the browser is considered an implementation detail (we could bundle/minimize the css for instance).
+
+Putting the `assets` directory 1 level higher than the `pages` directory avoids name collision with pages.
+
+
+Although the `assets` directory can be used for serving arbitrary files, we recommend using the [static files](/documentation/advanced/reference/static-files) directory instead, to avoid name collisions.
+
+
+## Extra asset locations
+
+If for instance you are creating a library on top of Solara, you might want to have your own assets files, like stylesheets or JavaScript files.
+For this purpose, solara-server can be configured to look into other directories for assets files by setting the `SOLARA_ASSETS_EXTRA_LOCATIONS` environment variable.
+This string contains a comma-separated list of directories or Python package names to look for asset files. The directories are searched in order, after looking in the application specific directory, and the first file found is used.
+
+For example, if we run solara as:
+
+```
+$ export SOLARA_ASSETS_EXTRA_LOCATIONS=/path/to/assets,my_package.assets
+$ solara run solara.website.pages
+Solara server is starting at http://localhost:8765...
+```
+
+And we would fetch `http://localhost:8765/static/assets/my-image.jpg`, Solara-server would look for the file in the following order:
+
+1. `.../solara/website/assets/my-image.jpg`
+1. `/path/to/assets/my-image.jpg`
+1. `.../my_package/assets/my-image.jpg`
+1. `...site-package/solara/server/assets/my-image.jpg`
+
+## Recommended pattern for libraries to add asset locations
+
+If you are creating a library on top of Solara, and you want to programmatically add asset locations, you can do so by adding the following code to your library:
+
+```python
+import solara.server.settings
+import my_package.assets
+
+
+path = my_package.assets.__path__[0]
+# append at the end, so SOLARA_ASSETS_EXTRA_LOCATIONS can override
+solara.server.settings.assets.extra_locations.append(path)
+```

solara/website/pages/documentation/advanced/content/15-reference/60-static-site-generation.md

@@ -0,0 +1,59 @@
+---
+title: Generating a static site version of your app or dashboard
+description: Solara's static site generation (SSG) feature allows you to pre-render HTML for your app or dashboard, improving the user experience by providing quick page loads.
+---
+## Static Site Generation
+## Introduction
+Solara's static site generation (SSG) feature allows you to pre-render HTML for your website, improving the user experience by providing quick page loads. When a user requests a page, the pre-rendered HTML is served directly to the user. After the page is displayed, the Solara server will connect and take over rendering to make the page interactive.
+
+Using SSG is mostly useful when the content of your website is the same for all users. This is the case for this page (the Solara page itself).
+
+## Benefits of SSG
+Another benefit of using SSG is improved search engine optimization (SEO). By allowing web crawlers to index your pages, you can improve the visibility of your website in search engine results.
+
+In addition to improving SEO, using SSG can also help with indexing your pages and making them more easily discoverable by users.
+
+## Using Solara's SSG feature.
+
+### Requirements
+
+Using SSR requires installation of [Playwright for Python](https://playwright.dev/python/). Follow their [installation instructions](https://playwright.dev/python/docs/library) or simply execute:
+
+
+```
+$ pip solara-enterprise[ssg]
+$ playwright install
+```
+
+### Pre-deployment
+
+Using the command
+
+```
+$ solara ssg your.awesome.app
+```
+
+Will run the solara server and use playwright to fetch all known pages and save them to the `../build` directory. Solara knows about your pages because of its [routing support](/documentation/advanced/understanding/routing).
+
+All HTML files in the `../build` will be used to pre-populate the HTML served to the user.
+
+### During deployment
+
+For fast and simpler deployment, you can also add the `--ssg` flag to the `solara run` command, e.g.:
+
+```
+$ solara run our.awesome.app --ssg
+```
+
+This will start you server immediately, and start a thread in the background that will fetch the known pages and put the in the `../build` directory, similar to the [pre-deployment](#pre-deployment) procedure.
+
+
+The downsides of this method, is that users or crawlers may request a page when SSR is not done yet, leading to a slower page load or missing content for the crawler.
+
+## Configuration
+
+### Environment variables
+
+ * `SOLARA_SSG_BUILD_PATH`: Override the directory where there html pages are stored.
+ * `SOLARA_SSG_ENABLED`: Alternative to passing the `--ssg` flag. Should be used when running solara without `solara run` (e.g. using gunicorn/uvicorn).
+ * `SOLARA_SSG_HEADED`: Run playwright using `headed` mode (in contrast to `headless`). Useful for debugging.

solara/website/pages/documentation/advanced/content/15-reference/70-search.md

@@ -0,0 +1,34 @@
+---
+title: Incorporating search into your Solara application
+description: If you are using static site generation (SSG) in your Solara application, you can make use of our search feature for it too!
+---
+# Search
+
+Solara can provide search, if [SSG](/documentation/advanced/reference/static-site-generation) is enabled. This allows you to add a search box to you website, which performs a full-text search to provide quick access to pages. The solara website itself uses the
+search feature as well in the toolbar.
+
+## Using Solara's Search feature.
+
+By running `solara run myapp.pages --ssg --search` solara will fetch all your pages, and build up a search index afterards. This option can also be abled using the environment variable `SOLARA_SEARCH_ENABLED=True`.
+
+You can import as use the Search component as follow:
+
+```
+import solara
+from solara_enterprise.search.search import Search
+
+
+@solara.component
+def Page():
+    with MyToolbar():
+        ...
+        Search()
+```
+
+## Requirements
+
+This feature requires `solara-enterprise`, which can be installed as follows:
+
+```
+pip install solara-enterprise
+```

solara/website/pages/documentation/advanced/content/15-reference/80-reloading.md

@@ -0,0 +1,34 @@
+---
+title: Automatic reloading of source files when developing with Solara
+description: Solara automatically detects changes in certain source file types, and hot reloads your application when you save them.
+---
+# Reloading
+
+## Reloading of Python files
+
+Solara will auto detect if your script or the sourcecode of an imported module has changes. If so, Solara will reload the page.
+
+(*Note: Upgrade to solara 1.14.0 for a fix in hot reloading using `pip install "solara>=1.14.0"`*)
+
+## Reloading of .vue files
+
+The solara server automatically watches all `.vue` files that are used by vue templates (there are some used in solara.components for example).
+When a `.vue` file is saved, the widgets get updated automatically, without needing a page reload, aiding rapid development.
+
+## Reloading of .vue files
+
+The [Style component](/documentation/components/advanced/style) accepts a Path as argument, when that is used and the server is in development mode (the default), also
+CSS files will be hot reloaded.
+
+
+## Restarting the server after changes to the solara packages
+
+
+You don't need to care about this feature if you only use solara, this is only relevant for development on solara itself, [see also development instructions](/documentation/advanced/development/setup).
+
+If the `--auto-restart/-a` flag is passed to solara-server and any changes occur in the `solara` package (excluding `solara.webpage`), solara-server will restart. This speeds up development on `solara-server` for developers since you do not
+need to manually restart the server in the terminal.
+
+## Disabling reloading
+
+In production mode (pass the `--production` argument to `solara run`) watching of files is disabled, and no reloading of files or vue templates will occur. If you run solara integrated in flask or uvicorn as laid out in [deployment documentation](https://solara.dev/documentation/getting_started/deploying/self-hosted)

solara/website/pages/documentation/advanced/content/15-reference/90-notebook-support.md

@@ -0,0 +1,7 @@
+---
+title: Using Solara within notebooks
+description: Solara can be used to generate an interactive app directly using your notebook file by running just one command.
+---
+# Notebook support
+
+We also support notebooks, simply assign to the `Page` variable in a code cell, save your notebook, and run `$ solara run myapp.ipynb`. If you widget or component is called differently, run like `$ solara run myapp.ipynb:myobject.nested_widget`.

solara/website/pages/documentation/advanced/content/15-reference/95-caching.md

@@ -0,0 +1,148 @@
+---
+title: Caching resources for your solara application or dashboard
+description: Solara has a dict-like object at `solara.cache.storage` that can be used to store objects in under a key. So we can use this global
+    object as normal dict.
+---
+# Caching
+
+Solara has a dict-like object at `solara.cache.storage` that can be used to store objects in under a key. So we can use this global
+object as normal dict, e.g.:
+
+```python
+import solara
+solara.cache.storage["my-key"] = expensive_function_call()
+assert "my-key" in solara.cache.storage
+```
+
+Note that at any time later on, the key may be removed from this object, as a cache always has a limited capacity.
+
+The `solara.cache.storage` cache object is used by [memoize](/documentation/api/utilities/memoize), if no storage argument is passed to this decorator.
+
+## Types of cache
+
+Solara core comes by default with an in-memory cache using a [LRU](https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)) (Least recently used) strategy. When the
+cache becomes too full, this removes entries used least recently.
+
+The cache is set by default to:
+```python
+solara.cache.storage = solara.cache.Memory(maxsize=128)
+```
+
+Which will remove the least recently used element when the 129th item is added.
+
+The memory cache is also configurable using environment variable:
+```
+$ export SOLARA_CACHE=memory  # already the default
+$ export SOLARA_CACHE_MEMORY_MAX_ITEMS=128  # already the default
+```
+
+## Custom caches
+An infinite cache can be set using:
+
+```python
+solara.cache.storage = {}  # a regular dict
+```
+
+The [cachetools](https://cachetools.readthedocs.io/) project has some caching types that behave like a Python dict, and are compatible with Solara, e.g.:
+
+```python
+import cachetools
+import solara
+solara.cache.storage = cachetools.FIFOCache(maxsize=100)
+```
+
+## Solara-enterprise
+
+With solara-enterprise, we have more cache storage options.
+
+### Memory (byte size based)
+
+The cache will limit the total number of bytes to a set maximum, instead of the number of items as is with the normal 'memory' cache.
+
+This can be set using code:
+
+```python
+import solara
+solara.cache.configure("memory-size")
+# or more explicit
+import solara_enterprise.cache.memory_size
+solara.cache.storage = solara_enterprise.cache.memory_size.MemorySize(
+    max_size="1GB"  # already the default
+)
+```
+
+The 'memory-size' cache can also be configured using environment variables:
+
+```
+$ export SOLARA_CACHE=memory-size
+$ export SOLARA_CACHE_MEMORY_MAX_SIZE=1GB  # already the default
+
+```
+
+
+### Disk cache
+
+This cache will persist the entries to disk, allowing multiple processes to share the same data. This cache type is ideal when using multiple workers on a single node.
+
+This can be set using code:
+
+```python
+import solara
+solara.cache.configure("disk")
+# or more explicit
+import solara_enterprise.cache.disk
+solara.cache.storage = solara_enterprise.cache.disk.Disk(
+    max_size="10GB", path="/home/maarten/.solara/cache"  # already the default
+)
+```
+
+Or configurable using environment variable:
+```
+$ export SOLARA_CACHE=disk
+$ export SOLARA_CACHE_DISK_MAX_SIZE=10GB  # already the default
+$ export SOLARA_CACHE_PATH_=/home/maarten/.solara/cache  # already the default
+```
+
+### Redis cache
+
+This cache will store the entries in a [Redis](https://redis.io/) server, allowing multiple nodes to share the same data. This is ideal in a cluster/distributed configuration.
+
+This can be set using code:
+
+```python
+import solara
+solara.cache.configure("redis")
+# or more explicit
+import solara_enterprise.cache.redis
+# optionally pass in a redis.Client object
+solara.cache.storage = solara_enterprise.cache.redis.Redis()
+```
+
+Or configured using environment variable:
+```
+$ export SOLARA_CACHE=redis
+```
+
+### Multi-level cache
+
+We can chain a few caches to get a multilevel cache. This allows us to get the benefits of the low latency memory cache while sharing it with other workers and nodes.
+
+```python
+import solara
+solara.cache.configure("memory,disk,redis")
+# or more explicit
+import solara_enterprise.cache.multi_level
+import solara_enterprise.cache.disk
+import solara_enterprise.cache.redis
+l1 = solara.cache.Memory()
+l2 = solara_enterprise.cache.disk.Disk()
+l3 = solara_enterprise.cache.redis.Redis()
+solara.cache.storage = solara_enterprise.cache.multi_level.MultiLevel(
+    l1, l2, l3
+)
+```
+
+Or configured using an environment variable:
+```
+$ export SOLARA_CACHE="memory,disk,redis"
+```

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

@@ -0,0 +1,10 @@
+---
+title: Understanding Solara's functionality
+description: Solara builds on existing technologies. If you are new to Solara or some of the underlying technologies, you may feel lost at times.
+    These 'understanding' guides are meant to help you understand topics at a deeper level and how they connect to Solara.
+---
+
+# Introduction
+
+Solara builds on existing technologies. If you are new to Solara or some of the underlying technologies, you may feel lost at times.
+These 'understanding' guides are meant to help you understand topics at a deeper level and how they connect to Solara.

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

@@ -0,0 +1,35 @@
+---
+title: Understanding how ipywidgets work together with Solara
+description: Solara's primarily standalone app approach differs from the ipywidgets one. This article dives deeper into the different approaches and adapting to using
+    ipywidgets within Solara.
+---
+# IPywidgets
+
+ * [Documentation](https://ipywidgets.readthedocs.io/en/stable/)
+ * [GitHub](https://github.com/jupyter-widgets/ipywidgets)
+
+IPywidgets is a Python library for creating UI objects that live in the Python side *and* on the browser side. They provide bi-directional communication, meaning you can change a slider in the browser, or from the Python side. `IPywidgets` takes care of communication and synchronization.
+
+With ipywidgets you get access to the browser without writing a single line of JavaScript or CSS.
+
+
+## Solara and ipywidgets
+
+Solara can use almost all existing ipywidgets, from the core library that provides sliders, to [ipyvuetify](./ipyvuetify) which gives us rich UI elements, to ipyvolume that gives us interactive 3d visualizations.
+
+## Where do ipywidgets work?
+
+There are various places where ipywidgets work, and [Solara server](./solara-server) is one of these. There is a [list of frontends that support](https://github.com/jupyter/jupyter/wiki/Jupyter-Widgets#frontends-that-support-jupyter-widgets) meaning that you ipywidgets based applications run
+on many places (From Jupyter Notebook, Jupyter Lab, Google Colab to even VS Code).
+
+## Which ipywidget libraries exist?
+
+There is a list [of ipywidget libraries](https://github.com/jupyter/jupyter/wiki/Jupyter-Widgets#custom-jupyter-widgets), but that are probably
+many more.
+
+
+## Do all ipywidget libraries work with Solara server?
+
+All these libraries should work with [Solara server](./solara-server), but we have not tested all of them. If you use a regular ipywidget based app, you should not run into issues. If you do, consider [opening a GitHub issue](https://github.com/widgetti/solara/issues/new)
+
+If you write a Reacton-based Solara application, check out [the reacton page](./reacton).

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

@@ -0,0 +1,42 @@
+---
+title: Using ipyvuetify widgets with Solara
+description: Ipyvuetify is an ipywidgets based library that wraps the Vuetify javascript framework for use with python widgets. Learn how to use these to build apps with Solara.
+---
+# ipyvuetify
+
+ * [Documentation](https://ipyvuetify.readthedocs.io/)
+ * [GitHub](https://github.com/widgetti/ipyvuetify)
+
+
+ipyvuetify is an [ipywidget based](./ipywidgets) library, that wraps the [Vuetify component library](https://v2.vuetifyjs.com/) to give beautiful
+material design based widgets.
+
+![ipyvuetify screencast demo](https://user-images.githubusercontent.com/46192475/79730684-78954880-82f1-11ea-855b-43a2b619ca04.gif)
+
+## Reacton and ipyvuetify
+
+We consider ipyvuetify one of the most essential ipywidget libraries, and that is the reason why [Reacton](/documentation/advanced/understanding/reacton) ships with
+generated ipyvuetify components to make your app type safe.
+
+```solara
+
+import solara
+# rv is the reacton-ipyvuetify wrapper for Reacton/Solara
+import reacton.ipyvuetify as rv
+
+
+@solara.component
+def Page():
+    clicks, set_clicks = solara.use_state(0)
+    def my_click_handler(*ignore_args):
+        # trigger a new render with a new value for clicks
+        set_clicks(clicks+1)
+    button = rv.Btn(children=[f"Clicked {clicks} times"])
+    rv.use_event(button, 'click', my_click_handler)
+    return button
+```
+
+
+## Solara and ipyvuetify
+
+Many of the Solara components are based on ipyvuetify. Do not hesitate the look at the [source code of the Solara components](https://github.com/widgetti/solara/tree/master/solara/components) to learn how to create your own components.

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

@@ -0,0 +1,28 @@
+---
+title: Understanding how Solara builds on Reacton
+description: Solara adapts the React way of using components declaratively to build UIs and brings it to Python.
+---
+# Reacton
+
+ * [Documentation](https://reacton.solara.dev/)
+ * [GitHub](https://github.com/widgetti/reacton/)
+
+Reacton is a React-like layer around ipywidgets.
+
+Using a declarative way, in a React (JS) style, makes your codebase smaller, less error-prone, and easier to reason about. We don't see a good reason not to use it.
+
+Also, React has proven itself, and by adopting a proven technology, we can stand on the shoulders of giants, make use of a lot of existing resources, and do not have to reinvent the wheel.
+
+
+## Solara or Reacton?
+
+We consider Solara a superset of Reacton, and that's why the full namespace of the `reacton` package is imported into the `solara` package.
+Therefore, you can write `solara.use_state` or `reacton.use_state`, they are the same function.
+
+The reason for this is simplicity for newcomers, who don't care about the difference between `solara` and `reacton`.
+But in practice, it also saves having to import both `solara` and `reacton`.
+Also, when writing Solara based apps, one does not think about Reacton anymore, it is all Solara.
+
+## How do I use Reacton or Solara with ipywidget library X
+
+[The reacton documentation has a page on this](https://reacton.solara.dev/en/latest/libraries/)

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

@@ -0,0 +1,108 @@
+---
+title: Understanding the basics of Reacton
+description: Using your favorite component, we try to understand better how it works to improve your understanding of Reacton and, thus, how to use Solara.
+---
+# Reacton basic understanding
+
+
+Let us take our favorite component, and try to understand a bit better how it works to improve your understanding of Reacton and thus how to use Solara.
+
+
+```solara
+import solara
+
+
+@solara.component
+def ClickButton():
+    clicks, set_clicks = solara.use_state(0)
+
+    def my_click_hander():
+        set_clicks(clicks + 1)
+
+    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
+
+Page = ClickButton
+```
+
+This example does a few things:
+
+ * Add state (`clicks`) to the component.
+ * Create a callback function (`my_click_handler`). When executed, it will increase ask Solara/Reacton to increase the `clicks` value on the next render, by calling `set_clicks`.
+ * Pass the callback function to the child component (`Button`).
+ * Set the `label` value on each render.
+
+Now if a user clicks the button:
+
+ * The `my_click_hander` callback will be called by Solara/Reacton.
+ * Your code (the body of `my_click_hander`) will be executed and will ask Reacton to change the state of `clicks` by increasing the value by 1.
+ * Solara/Reacton got asked to change the of `clicks`, and will execute your render function (the body of the `ClickButton` component) once.
+ * Solara/Reacton will compare the return value of your component and will update the associated widget. In this case it will update the label to `"`Clicked: 1"`.
+
+This pattern is very common, where a parent component (ClickButton) managed the state (the number of times clicked), and state changes (increasing the clicks by 1 on a button click).
+
+## Graphically
+
+Is the above text a bit dry? Maybe the annotated code will make it easier to understand for you.
+
+![basics](https://dxhl76zpt6fap.cloudfront.net/public/docs/reacton-basics.webp)
+
+
+## Going deeper
+
+
+Still not satisfied? Let's go through all the steps in more detail in this sequence diagram:
+
+```mermaid
+sequenceDiagram
+    actor You
+    participant Frontend as Frontend
+    participant ipywidgets as IPyWidgets
+    participant react as Reacton
+    participant component as ButtonClick
+    participant app as Solara
+
+    app->>component: el=ButtonClick()
+    app->>react: render(el)
+
+    activate react
+    react->>component: render()
+    component->>react: use_state(0)<br>(returns 0)
+
+    react->>react: reconsolidate()
+    react->>ipywidgets: create Button<br>description="Clicked: 0"
+    deactivate react
+    ipywidgets--)Frontend: create Button view
+
+    You->>Frontend: clicks button
+
+    Frontend--)ipywidgets: Button clicked
+    ipywidgets->>component: on_click
+    activate component
+    component->>react: set_clicks(1)
+    activate react
+    deactivate component
+    react->>+component: render()
+    component->>-react: use_state(0)<br> (now returns 1)
+    react->>react: reconsolidate()
+    react->>ipywidgets: update Button<br>description="Clicked 1"
+    deactivate react
+    ipywidgets--)Frontend: update Button<br>description="Clicked 1"
+```
+
+In words
+
+   1. Solara create `el = ButtonClick()` from your component.
+   1. The `display(el)` triggers the call to Reacton.
+   1. The render call enters the render phase, which will call the function body (which we call render function) of the `ButtonClick` component.
+   1. Our ButtonClick render function calls [`use_state`](/documentation/api/hooks/use_state). Because this is our first render phase, this returns the initial value (0).
+   1. The ButtonClick render function returns a Button element (not a widget!) with `description="Clicked: 0 times"`.
+   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is no previous widget associated with the virtual widget (or element) and decide to create a widget.
+   1. Asynchronously via the Jupyter protocol, a widget model and view are created and displayed to the user in the browser.
+   1. The user clicks on the button.
+   1. The `on_click` handler gets triggered on the Python side, inside of the `ButtonClick` component (called `my_click_handler`).
+   1. `my_click_handler` handler calls `set_clicks(1)` which triggers a re-render.
+   1. The render call enters the render phase, which calls the render function of `ButtonClick` for the second time.
+   1. Our ButtonClick render function calls [`reacton.use_state`](#use_state). Because this is our second render phase, this returns the last set value, which is 1.
+   1. The ButtonClick render function returns a new Button element (not a widget!) with the description `"Clicked: 1 times"`.
+   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is a widget associated with the virtual widget (or element) and decide to update the changed attributes of the widget and set `description` to `"Clicked: 1 times"`.
+   1. Asynchronously via the Jupyter protocol, the widet model and view are being updated in the browser.

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

@@ -0,0 +1,23 @@
+---
+title: The anatomy of Solara's functionality
+description: Dive deep into how Solara uses the technologies it builds on.
+---
+# Anatomy
+
+For communication, it is useful to speak the same language and use the same idiom.
+As a reference, we provide this "anatomy" image of our favorite `ClickButton` component with a layout that we consider best practice.
+
+![anatomy](https://dxhl76zpt6fap.cloudfront.net/public/docs/anatomy.webp)
+
+## Explanations
+
+ * Import `solara` and you also get the `reacton` namespace with it (saves typing, and finding/remembering which hooks is in which packages)
+ * Add a `@solara.component` decorator to turn your function into a component.
+ * Start with `use_state` hooks and other hooks. This avoids issues with [conditional hooks](/documentation/advanced/understanding/rules-of-hooks) or hooks in loops.
+ * Data/state flows down (to children)
+ * Information (events, data) flows up from children via events and callbacks (`on_<some_event_name>=my_callback`).
+ * If you need multiple components, use a [parent container component](/documentation/components/layout/app_layout) as context manager. A good default name to give this context manager is `main`. Don't forget to return it in your render function!
+ * The body of your component (the function you wrote) is called the render function.
+ * In between the hooks as defining all your elements, you put your custom code, like checking variables, defining callbacks, and other logic.
+ * The only way for a component to cause itself to rerender is to have state (using `use_state`) and change it (calling the second return value with a different value).
+ * Reacton is declarative. Your render function gets executed after every state change (and thus should be relatively cheap to execute). Reacton will find out the changes for you and will add, remove and update the associated widgets for you. This means you can easily do conditional rendering (creating an element in an if statement or in a loop).