solara-ui 1.45.0__py3-none-any.whl

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

@@ -0,0 +1,108 @@
+---
+title: Understanding the way Solara server works
+description: Solara server enables running ipywidgets-based applications as standalone dashboards and apps, allowing multiple "Virtual kernels" to share
+   the same process for better performance and scalability.
+---
+# Solara server
+
+The solara server enables running ipywidgets based applications without a real Jupyter kernel, allowing multiple "Virtual kernels" to share the same process for better performance and scalability.
+
+## Installation
+
+To install the solara server, run:
+
+```bash
+$ pip install "solara-server[starlette]"
+$ # pip install solara # to get all solara packages
+```
+
+See [our installation guide](/documentation/getting_started/installing) for more information.
+
+## WebSocket in Solara
+Solara uses a WebSocket to transmit state and updates directly from the server to the browser. This ensures that the state remains centralized on the server, facilitating state transitions server-side and enabling live updates to be pushed directly to the browser.
+
+
+## Virtual Kernels
+Normally when a browser page connects to a Solara server, a virtual kernel is created and is assigned a unique identifier termed a "Kernel ID." Should a WebSocket disconnection occur, Solara attempts to re-establish the connection, sending the Kernel ID during this process. If the server recognizes this ID (and the requested kernel hasn't expired) the Solara app resumes operations seamlessly.
+
+### Virtual kernel lifecycle
+Closing a browser page will directly shut the virtual kernel down (if this page was the last known page to the Solara server). This ensures that active closing of pages will directly clean up any memory usage on the server side for this kernel.
+
+However, when the websocket between the web page and the server disconnects, the server keeps the kernel alive for 24 hours after the closure of the last WebSocket connection. The duration is customizable through the `SOLARA_KERNEL_CULL_TIMEOUT` environment variable. This feature is particularly handy in scenarios where devices like computers hibernate, leading to WebSocket disconnections. Upon awakening and subsequent WebSocket reconnection, the Solara app picks up right where it left off.
+
+To optimize memory usage or address specific needs, one might opt for a shorter expiration duration. For instance, setting `SOLARA_KERNEL_CULL_TIMEOUT=1m` will cause sessions to expire after just 1 minute. Other possible options are `2d` (2 days), `3h` (3 hours), `30s` (30 seconds), etc. If no units are given, seconds are assumed.
+
+### Maximum number of kernels connected
+
+Each virtual kernel runs in its own thread, this ensures that one particular user (actually browser page) cannot block the execution of another virtual kernel. However, each thread consumes a bit of resources. If you want to limit the number of kernels, this can be done by setting the `SOLARA_KERNELS_MAX_COUNT` environment variable. The default is unlimited (empty string), but you can set it to any number you like. If the limit is reached, the server will refuse new connections until a kernel is closed.
+
+
+## Handling Multiple Workers
+
+In setups with multiple workers, it's possible for a page to (re)connect to a different worker than its original. This can happen after a lost network connection is restored, or when [ipypopout](https://github.com/widgetti/ipypopout) is used, since ipypopout creates a new connection, which can end up at a different worker. This can result in a loss of the virtual kernel, since it lives on the worker that was first connected to. The Solara app will then initiate a fresh start, or simply fail when ipypopout is used. To prevent this scenario, a sticky session configuration is recommended, ensuring consistent client-worker connections. A load balancer, such as [nginx](https://www.nginx.com/), can be used to achieve this. Note that using multiple workers (e.g. by using gunicorn) cannot work since a connection will be made to a different worker each time.
+
+If you have questions about setting this up, or require assistance, please [contact us](https://solara.dev/docs/contact).
+
+## Sessions
+
+Solara uses a browser cookie (named `solara-session-id`) to store a unique session id. This session id is available via [get_session_id()](https://solara.dev/api/get_session_id) and is the same for all
+browser pages. This can be used to store state that outlives a page refresh.
+
+We recommend storing the state in an external database, especially in the case of multiple workers/nodes. If you want to store state associated to a session in-memory, make sure to set up sticky sessions.
+
+
+The `solara-session-id` cookie is accessible in the browser using JavaScript. If you deem this a security risk, you can disable the cookie by setting the `SOLARA_SESSION_HTTP_ONLY` environment variable to `True`.
+
+
+## Readiness check
+
+To check if the server is ready to accept request, the `/readyz` endpoint is added, and should return a 200 HTTP status code, e.g.:
+
+```
+$ curl http://localhost:8765/readyz
+curl -I localhost:8765
+
+HTTP/1.1 200 OK
+...
+```
+
+## Live resource information
+
+
+To check resource usage of the server (CPU, memory, etc.), the `/resourcez` endpoint is added, and should return a 200 HTTP status code and include
+various resource information, like threads created and running, number of virtual kernels, etc. in JSON format. To get also memory and cpu usage, you can include
+the `?verbose` query parameter, e.g.:
+
+```
+$ curl http://localhost:8765/resourcez\?verbose
+```
+
+The JSON format may be subject to change.
+
+## Ignoring notebook extensions
+
+Not all (classic) jupyter notebook extensions are compatible with Solara, and there is not way to distinguish between notebook extensions that are needed for widgets and those that are not.
+To ignore notebook extensions, you can set the `SOLARA_SERVER_IGNORE_NBEXTENSIONS` environment variable. This is a comma separated list of notebook extensions to ignore. For example, to ignore the `dash/main` and `foo/bar` extensions, you can run:
+
+```bash
+$ SOLARA_SERVER_IGNORE_NBEXTENSIONS="dash/main,foo/bar" solara run nogit/sol.py -a
+```
+
+Note that these error are not fatal, and the Solara app will still run.
+
+## Production mode
+
+By default, solara runs in development mode. This means, it will:
+
+   * Automatically [reload your project files](/documentation/advanced/reference/reloading) by watching files on the filesystemn
+   * Load debug version of the CSS files and JavaScript files for improved error messages (which leads to larger asset files).
+
+To disabled all of these option, pass the `--production` flag, or set the environment variable `SOLARA_MODE=production`.
+
+## Telemetry
+
+Solara uses Mixpanel to collect usage of the solara server. We track when a server is started, stopped and a daily report of the number of unique users and connections made. To opt out of mixpanel telemetry, either:
+
+ * Set the environmental variable `SOLARA_TELEMETRY_MIXPANEL_ENABLE` to `False`.
+ * Install [python-dotenv](https://pypi.org/project/python-dotenv/) and put `SOLARA_TELEMETRY_MIXPANEL_ENABLE=False` in a `.env` file.
+ * Run in auto restart mode (e.g. using `$ solara run sol.py --auto-restart`)

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

@@ -0,0 +1,12 @@
+---
+title: Working together with Voilà
+description: Voilà, together with `voila-vuetify` is an alternative to Solara server. The most significant difference is that Voilà will start one kernel/process
+    per page request, while Solara server is more scalable.
+---
+# Voilà
+
+[Voilà](https://voila.readthedocs.io/) allows you to convert a Jupyter Notebook into an interactive dashboard that allows you to share your work with others.
+
+Voilà is Jupyter notebook focused, meaning that it will render all output from your notebook. Using [`voila-vuetify`](https://github.com/voila-dashboards/voila-vuetify) Voilà allows for a more app like experience, showing only the output you want.
+
+Voilà, together with `voila-vuetify` is an alternative to [Solara server](./solara-server). The most significant difference is that Voilà will start one kernel/process per page request, while [Solara server](./solara-server) can serve many more users from a single process. Sharing the same process means Solara apps can share memory among users (e.g. a large dataset), which will usually lead to better performance and less resource usage.

solara/website/pages/documentation/advanced/content/30-enterprise/00-overview.md

@@ -0,0 +1,7 @@
+# Solara enterprise
+
+Solara enterprise is a not Open Source, but the source code is visible, is free for non-commercial use and installable from pypi.
+
+For commercial use, you require a license. Please see [pricing](/pricing) for more information.
+
+Solara-enterprise will stay free for non-commercial use and features that are in solara will **not be moved to solara-enterprise**.

solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md

@@ -0,0 +1,187 @@
+---
+title: Using OAuth in your Solara app
+description: Open Authorization can be readily integrated into your Solara applications via the Solara-Enterprise package.
+---
+# OAuth: authentication and authorization support
+
+## What is OAuth
+
+OAuth (Open Authorization) is an open standard for token-based authentication and authorization. It enables third-party applications to obtain limited access to a user's resources on another service without exposing their credentials. The user can grant access to their resources on one site to another site without sharing their credentials, providing a secure and efficient way to authenticate users.
+
+You have probably used OAuth without realizing it when signing into various online services and applications. For example, when you use "Sign in with Google" or "Log in with Facebook" to access a third-party website or application, you are using OAuth. By leveraging OAuth, these services allow users to authenticate themselves using their existing Google or Facebook credentials, simplifying the login process and reducing the need for users to remember multiple usernames and passwords. OAuth has become an essential aspect of online identity management and is widely used by companies and developers to provide a seamless and secure authentication experience.
+
+## Installing
+
+To install Solara with OAuth support, make sure you have [Solara Enterprise](/documentation/advanced/enterprise) install by run the following command:
+
+```bash
+$ pip install solara solara-enterprise[auth]
+```
+
+
+## OAuth support in Solara
+
+Solara offers two modes for enabling OAuth: private mode and application controlled mode.
+
+### Private mode
+
+In private mode, Solara pages or any static resources are not accessible without being authenticated. This mode is suitable for web servers that should not be publicly accessible. To enable private mode, set the following environment variable:
+```bash
+SOLARA_OAUTH_PRIVATE=True
+```
+
+
+### Application controlled mode
+
+In application controlled mode, the application is responsible for checking if a user is authenticated. The application can show a login or logout link and provide user information when the user is logged in. Solara comes preconfigured to run on localhost out of the box, and no additional setup is required to enable OAuth for local development and testing.
+
+Here's an example of how to implement OAuth in application controlled mode:
+
+```solara
+import solara
+from solara_enterprise import auth
+
+@solara.component
+def Page():
+    if not auth.user.value:
+        # `get_login_url` should automatically redirect the user back to the current page.
+        # The URL argument is only used here as an example.
+        solara.Button("Login", icon_name="mdi-login", href=auth.get_login_url("documentation/advanced/enterprise/oauth"))
+    else:
+        userinfo = auth.user.value['userinfo']
+        if 'name' in userinfo:
+            solara.Markdown(f"### Welcome {userinfo['name']}")
+        # See above comment
+        solara.Button("Logout", icon_name="mdi-logout", href=auth.get_logout_url("documentation/advanced/enterprise/oauth"))
+```
+## How to configure OAuth
+
+Solara currently supports [Auth0](https://auth0.com/) as the sole OAuth provider. [Fief](https://fief.dev/) support is **deprecated** (currently untested), but is not planned to be removed. If you would like support for a different provider to be added, [contact us](/contact)
+
+
+### Configuring Auth0
+
+By default, Solara is configured with a test Auth0 account. This is useful for testing, but you should not use this in production. This account does limit solara running on localhost, port 8765 to 8770 (and 18765 to 18770 for running the tests).
+
+To configure your own Auth0 provider, you need to change the following environment variables from their defaults:
+
+```bash
+# required if you don't use the default test account
+SOLARA_SESSION_SECRET_KEY="change me"
+# found in the Auth0 dashboard Applications->Applications->Client ID
+SOLARA_OAUTH_CLIENT_ID="cW7owP5Q52YHMZAnJwT8FPlH2ZKvvL3U"
+# found in the Auth0 dashboard Applications->Applications->Client secret
+SOLARA_OAUTH_CLIENT_SECRET="zxITXxoz54OjuSmdn-PluQgAwbeYyoB7ALlnLoodftvAn81usDXW0quchvoNvUYD"
+# found in the Auth0 dashboard Applications->Applications->Domain
+SOLARA_OAUTH_API_BASE_URL="dev-y02f02f2bpr8skxu785.us.auth0.com"
+```
+
+You can optionally set the following environment variables:
+
+```bash
+SOLARA_OAUTH_SCOPE = "openid profile email"
+```
+
+### Create your own Auth0 Application
+
+
+To create your own Auth0 application, follow these steps:
+
+1. Go to the [Auth0 dashboard](https://manage.auth0.com/dashboard/) and click on "Applications" on the left side navigation menu.
+
+    ![Auth0 dashboard](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/goto-applications.webp)
+
+2. Click on "Create Application".
+
+    ![Create Application](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/click-create-application.webp)
+
+3. Enter a name for your application and select "Regular Web Applications" as the application type. Click on "Create".
+
+    ![Create Application](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/name-type-create.webp)
+
+4. Click "Skip Integration" to skip the integration step.
+
+5. Click on the "Settings" tabs and enter the following information:
+
+    - Allowed Callback URLs: `http://localhost:8765/_solara/auth/authorize, https://yourdomain.com/_solara/auth/authorize`
+    - Allowed Logout URLs: `http://localhost:8765/_solara/auth/logout, https://yourdomain.com/_solara/auth/logout`
+
+    Note that the localhost URLs are only meant for testing. You can remove them once you are ready to deploy your application.
+    We recommend setting up a new application for each environment (e.g. development, staging, production).
+
+    ![Callback URLs](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/callbacks.webp)
+
+6. Configure Solara.
+
+    At the top of the "Settings" tab, you should see your "Domain", "Client ID" and "Client Secret". You will need to set the following environment variables to these values:
+
+    ```bash
+    SOLARA_OAUTH_API_BASE_URL="dev-y02f2bpr8skxu785.us.auth0.com"  # replace with your domain
+    SOLARA_OAUTH_CLIENT_ID="ELOFERLovc7e7dPwkxO6WFAljtYj9UzJ"  # replace with your client ID
+    SOLARA_OAUTH_CLIENT_SECRET="..."  # not shown here, replace with your client secret
+    ```
+
+    ![Settings](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/configuration-values.webp)
+
+    Set your `SOLARA_SESSION_SECRET_KEY` to a random string. See the [Generating a secret key](#generating-a-secret-key) for a convenient way to generate a secret key.
+
+    Solara forces you to set a value for `SOLARA_SESSION_HTTPS_ONLY`, because the OAuth login is only secure when this setting is `True` and your app runs over HTTPS.
+    For development, where your app likely doesn't run over HTTPS, you must set it to `False`, otherwise OAuth login will not work.
+    For more information on configuring Solara to run over HTTPS, see [HTTPS](/documentation/getting_started/deploying/self-hosted#https).
+
+    Now you can run the above solara example using your own auth0 provider.
+
+
+### Configuring Fief
+
+##### Note: Fief support is not maintained or tested. If you would like Fief to be supported, feel free to [contact us](/contact)
+
+You can also configure Solara to use our Fief test account. To do this, you need to set the following environment variables:
+
+```bash
+SOLARA_SESSION_SECRET_KEY="change me"  # required if you don't use the default test account
+SOLARA_OAUTH_CLIENT_ID="x2np62qgwp6hnEGTP4JYUE3igdZWhT-AvjpjwwDyKXU"  # found in the Auth0 dashboard Clients->General Tab->ID
+SOLARA_OAUTH_CLIENT_SECRET="XQlByE1pVIz5h2SBN2GYDwT_ziqArHJgLD3KqMlCHjg" # found in the Auth0 dashboard Clients->General Tab->Secret
+SOLARA_OAUTH_API_BASE_URL="solara-dev.fief.dev"  # found in the Fief dashboard Tenants->Base URL
+ # different from Solara's default
+SOLARA_OAUTH_LOGOUT_PATH="logout"
+```
+
+### Generating a secret key
+
+To generate a secret key, you can use the following code:
+
+```bash
+$ python -c "import secrets; print(secrets.token_urlsafe(32))"
+ZgrzSLUyft-JvnNMNJ2LgbCFVqcxPOatANAQhMD5EYU
+```
+
+*Note: do not copy this key, run this yourself in a terminal.*
+
+
+## OAuth Component
+
+Solara provides two convenient components for creating a user interface for login and logout:
+
+ 1. [Avatar](/documentation/components/enterprise/avatar): This component shows the user's avatar.
+ 2. [AvatarMenu](/documentation/components/enterprise/avatar_menu): This component shows a menu with the user's avatar and a logout button.
+
+## Python version support
+
+Please note that Python 3.6 is not supported for Solara OAuth.
+
+
+## Possible issues
+
+### Wrong redirection
+
+If the redirection back to solara return to the wrong address, it might be due to solara not choosing the right default for `SOLARA_BASE_URL`. This can happen in a situation where you have multiple reverse proxies that communicate via https and therefore need to set the Host header. For instance this variable could be set to `SOLARA_BASE_URL=https://solara.dev` for the solara.dev server. If you application runs behind a subpath, e.g. `/myapp`, you might have to set `SOLARA_ROOT_PATH=/myapp`.
+
+
+### Wrong schema detected for redirect URL
+
+Solara needs to give the OAuth providers a redirect URL to get back to your Solara application after navigating to the OAuth provider website. For our documentation server, we ask the OAuth provider to redirect to `https://solara.dev/_solara/auth/authorize`. The protocol part (`https`) and the domain name part (`solara.dev`) of this URL is constructed from the request (what the browser sends to the server).
+
+If you are running Solara behind a reverse proxy server (like nginx), make sure that the `X-Forwarded-Proto` and `Host` headers are forwarded correctly, and the proxy server is trusted by uvicorn (by configuring the `FORWARDED_ALLOW_IPS` environment variable) so Solara can construct the correct redirect URL to send to the OAuth provider.
+
+See our [self hosted deployment](https://solara.dev/documentation/getting_started/deploying/self-hosted) for more information on how to configure your reverse proxy server.

solara/website/pages/documentation/advanced/content/40-development/01-contribute.md

@@ -0,0 +1,45 @@
+---
+title: Contributing to Solara
+description: You do not need to be a developer to contribute to Solara. We welcome all contributions, bug reports, documentation improvements and code contributions.
+---
+# Contributing to Solara
+
+You do not need to be a developer to contribute to Solara. We welcome all contributions, bug reports, documentation improvements and code contributions.
+
+
+## Bug reports
+
+We use [GitHub to manage issues](https://github.com/widgetti/solara/issues/new) and you should not hesitate to report any bug you find. Please include as much information as possible for us to be able to reproduce the bug. Yes, reporting a bug/issue is a contribution!
+
+It might take a while for us to get back to you. If the bug is urgent, and you are able to provide financial support for its rapid resolution, please [contact us](/contact).
+If you can fix the bug yourself, please consider submitting a pull request instead, see [the development guide](/documentation/advanced/development/setup) for more information.
+
+If you are unable to address the bug yourself and find it challenging to provide financial support, please be assured we are still committed to rectifying bugs and resolving issues. However, please understand that our ability to address these issues may be impacted by our resources at hand, as sustaining this project also entails financial obligations. Your patience and understanding in this matter is highly appreciated 🙇.
+
+## Documentation
+
+The documentation is mostly written in Markdown, and can be found at [in the main repository](https://github.com/widgetti/solara/tree/master/solara/website/pages).
+
+You can use the GitHub web interface to edit the files, or clone the repository and edit them locally. See [the development guide](/documentation/advanced/development/setup) for more information.
+
+If you locally want to render the documentation, run:
+
+```bash
+$ solara run solara.website.pages
+```
+
+## Examples or showcase
+
+If you have a complete program you want to share, and you think it would be cool to be listed at [our showcase page](/showcase), [please contact us](/contact).
+
+If you want to show a particular way of using Solara that you think is very useful
+for others, but it is not a complete program, consider adding to [the examples](/documentation/examples/). See [the development guide](/documentation/advanced/development/setup) for more information.
+
+## Share your experiences and ideas
+
+If you want to share your thoughts, share your experiences, or just want to talk
+to other people using and developing on Solara, consider using [GitHub discussions](https://github.com/widgetti/solara/discussions) for asynchronous discussions
+or consider joining discord for more synchronous discussions.
+
+
+[![Discord Shield](https://discordapp.com/api/guilds/1106593685241614489/widget.png?style=banner2)](https://discord.gg/dm4GKNDjXN)

solara/website/pages/documentation/advanced/content/40-development/10-setup.md

@@ -0,0 +1,76 @@
+---
+title: Development setup for Solara
+description: Learn how to set up your installation for developing on the Solara itself.
+---
+# Development
+
+See also [the contributing guide](/documentation/advanced/development/contribute) for more information on how to contribute to Solara.
+## Development setup
+
+Assuming you have created a virtual environment as described in [the installation guide](/documentation/getting_started/installing), you can install a development install of Solara using:
+
+    $ git clone git@github.com:widgetti/solara.git
+    $ cd solara
+    $ pip install -r requirements-dev.txt
+
+
+## Running Solara server in auto restart mode
+
+By passing the `--auto-restart/-a` flag, the solara server will automatically restart when the sourcecode of the solara server changes, which makes it friendlier for development
+
+    $ solara run myscript.py -a
+
+This will:
+
+    * Automatically restart the server if any of the source code of solara changes (excluding solara.website)
+
+## Contributing
+
+If you plan to contribute, also run the following:
+
+    $ pre-commit install
+
+This will cause a test of linters/formatters and mypy to run so the code is in good quality before you git commit.
+
+    $ playwright install
+
+This will install playwright, for when you want to run the integration tests.
+
+### Test suite
+
+If you want to run the unit tests (quick run when doing development, or when you do test driven development)
+
+    $ py.test tests/unit
+
+
+If you want to run the integration tests (uses playwright to open a browser to test the live server with a real browser)
+
+    $ py.test tests/integration
+
+Pass the `--headed` flag to see what is going on, [or check out the docs](https://playwright.dev/python/docs/intro)
+
+
+### Creating a PR
+
+Make sure you forked the repository, and set up the remote and origin correctly.
+
+```
+# rename origin to upstream
+$ git remote rename origin upstream
+# add your fork as origin
+$ git remote add origin https://github.com/yourusername/solara.git
+```
+
+Now we will create a branch, push it, and open a PR
+
+```
+# create a branch
+$ git checkout -b fix_some_thing
+# add whatever changes you want to make
+$ git add -p
+# commit your changes
+$ git commit -m "fix: some thing"
+# push your changes
+$ git push
+# click the link that is printed to open a PR
+```

solara/website/pages/documentation/api/__init__.py

@@ -0,0 +1,19 @@
+"""
+# Overview
+Click on one of the items on the left.
+"""
+
+import solara
+from solara.website.components import CategoryLayout, Gallery
+
+_title = "API"
+
+
+@solara.component
+def Page(route_external=None):
+    Gallery(route_external)
+
+
+@solara.component
+def Layout(children=[]):
+    CategoryLayout(children=children)

solara/website/pages/documentation/api/cross_filter/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/cross_filter/cross_filter_dataframe.py

@@ -0,0 +1,22 @@
+"""# CrossFilterDataFrame"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+title = "CrossFilterDataFrame"
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+
+    solara.CrossFilterReport(df, classes=["py-2"])
+    solara.CrossFilterSelect(df, "country")
+    solara.CrossFilterDataFrame(df)
+
+
+__doc__ += apidoc(solara.CrossFilterDataFrame.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_report.py

@@ -0,0 +1,20 @@
+"""# CrossFilterReport"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    solara.CrossFilterReport(df, classes=["py-2"])
+    solara.CrossFilterSelect(df, "country")
+    solara.CrossFilterSlider(df, "gdpPercap", mode=">")
+
+
+__doc__ += apidoc(solara.CrossFilterReport.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_select.py

@@ -0,0 +1,20 @@
+"""# CrossFilterSelect"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.tips()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    solara.CrossFilterReport(df, classes=["py-2"])
+    solara.CrossFilterSelect(df, "sex")
+    solara.CrossFilterSelect(df, "time")
+
+
+__doc__ += apidoc(solara.CrossFilterSelect.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_slider.py

@@ -0,0 +1,20 @@
+"""# CrossFilterSlider"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    solara.CrossFilterReport(df, classes=["py-2"])
+    solara.CrossFilterSlider(df, "pop", mode=">")
+    solara.CrossFilterSlider(df, "gdpPercap", mode="<")
+
+
+__doc__ += apidoc(solara.CrossFilterSlider.f)  # type: ignore

solara/website/pages/documentation/api/hooks/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/hooks/use_cross_filter.py

@@ -0,0 +1,23 @@
+"""# use_cross_filter"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+title = "use_cross_filter"
+
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    solara.CrossFilterReport(df, classes=["py-2"])
+    solara.CrossFilterSelect(df, "continent")
+    solara.CrossFilterSlider(df, "gdpPercap", mode=">")
+
+
+__doc__ += apidoc(solara.use_cross_filter)  # type: ignore

solara/website/pages/documentation/api/hooks/use_dark_effective.py

@@ -0,0 +1,12 @@
+"""# use_dark_effective"""
+
+import solara
+import solara.autorouting
+import solara.lab
+from solara.website.utils import apidoc
+
+from . import NoPage
+
+title = "use_dark_effective"
+Page = NoPage
+__doc__ += apidoc(solara.lab.use_dark_effective)  # type: ignore

solara/website/pages/documentation/api/hooks/use_effect.md

@@ -0,0 +1,43 @@
+# use_effect
+
+```python
+def use_effect(
+    effect: EffectCallable,
+    dependencies: Any | None = None
+) -> None
+    ...
+```
+
+Execute non-declarative code within a callback, for instance to add event handlers. `effect` is executed *after* page render, letting us fetch the actual underlying widget object using `solara.get_widget` on an element. `dependencies` should be a list of variables, which when changed trigger re-execution of `effect`. If left empty, `effect` will never re-execute.
+
+`effect` can return a cleanup function, which will be called before re-execution of `effect`, or when the component containing `use_effect` is removed.
+
+Example use of `use_effect` to attach an event handler to a solara component:
+
+```python
+def use_event(el: solara.Element, callback: Callable):
+    def add_event_handler():
+        def on_enter(widget, event, data):
+            callback(widget.v_model)
+
+        widget = cast(ipyvue.VueWidget, solara.get_widget(el))
+        widget.on_event("keyup.enter", on_enter)
+
+        def cleanup():
+            widget.on_event("keyup.enter", on_enter, remove=True)
+
+        return cleanup
+
+    solara.use_effect(add_event_handler, dependencies=[])
+
+@solara.component
+def Page():
+    def function():
+        #Do something...
+
+    input = solara.InputText():
+    use_event(input, function)
+    ...
+```
+
+See also the [Reacton docs](https://reacton.solara.dev/en/latest/api/#use_effect).