Merge branch 'zauberzeug:main' into main

Author: python-and-novella

nicegui/elements/sub_pages.py

@@ -33,8 +33,6 @@ def __init__(self,
         Routes are defined as path patterns mapping to page builder functions.
         Path parameters like "/user/{id}" are extracted and passed to the builder function.
 
-        **This is an experimental feature, and the API is subject to change.**
-
         *Added in version 2.22.0*
 
         :param routes: dictionary mapping path patterns to page builder functions

nicegui/sub_pages_router.py

@@ -43,8 +43,6 @@ def __init__(self, request: Request | None) -> None:
     def on_path_changed(self, handler: Callable[[str], None]) -> None:
         """Register a callback to be invoked when the path changes.
 
-        **This is an experimental feature, and the API is subject to change.**
-
         :param handler: callback function that receives the new path as its argument
         """
         self._path_changed_handlers.append(handler)

website/documentation/code_extraction.py

@@ -22,11 +22,16 @@ def get_full_code(f: Callable) -> str:
         while code[0].strip() != '"""':
             del code[0]
         del code[0]
-    indentation = len(code[0]) - len(code[0].lstrip())
+    non_empty_lines = [line for line in code if line.strip()]
+    indentation = len(non_empty_lines[0]) - len(non_empty_lines[0].lstrip())
     code = [line[indentation:] for line in code]
     code = ['from nicegui import ui'] + [_uncomment(line) for line in code]
     code = ['' if line == '#' else line for line in code]
-    if not code[-1].startswith('ui.run('):
+
+    if any(line.strip().startswith('def root(') for line in code):
+        code = [line for line in code if line.strip() != 'return root']
+        code.append('ui.run(root)')
+    elif not code[-1].startswith('ui.run('):
         code.append('')
         code.append('ui.run()')
     full_code = isort.code('\n'.join(code), no_sections=True, lines_after_imports=1)

website/documentation/content/sub_pages_documentation.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import Any, Awaitable, Callable, Dict, Optional
+from typing import Any, Awaitable, Callable, Optional
 
 from nicegui import PageArguments, background_tasks, ui
 
@@ -18,8 +18,8 @@ def init(self) -> None:
         self._render('/')
         self.move()  # move to end
 
-    def link(self, text: str, route: str, **kwargs: Any) -> None:
-        ui.label(text).classes('nicegui-link cursor-pointer').on('click', lambda: self._render(route, **kwargs))
+    def link(self, text: str, route: str, **kwargs: Any) -> ui.label:
+        return ui.label(text).classes('nicegui-link cursor-pointer').on('click', lambda: self._render(route, **kwargs))
 
     def _render(self, route: str, **kwargs: Any) -> None:
         if self.task and not self.task.done():
@@ -46,8 +46,6 @@ def __init__(self, **kwargs: Any) -> None:
     The `ui.sub_pages` element itself functions as the container for the currently active sub page.
     You only need to provide the routes for each view builder function.
     NiceGUI takes care of replacing the content without triggering a full page reload when the URL changes.
-
-    **NOTE: This is an experimental feature, and the API is subject to change.**
 ''')
 def main_demo() -> None:
     from uuid import uuid4

website/documentation/demo.py

@@ -24,13 +24,18 @@ def demo(f: Callable, *, lazy: bool = True, tab: Optional[Union[str, Callable]]
 
                 async def handle_intersection():
                     window.remove(spinner)
-                    if helpers.is_coroutine_function(f):
-                        await f()
-                    else:
-                        f()
+                    result = f()
+                    if callable(result):
+                        if helpers.is_coroutine_function(result):
+                            await result()
+                        else:
+                            result()
                 intersection_observer(on_intersection=handle_intersection)
             else:
-                assert not helpers.is_coroutine_function(f), 'async functions are not supported in non-lazy demos'
-                f()
+                result = f()
+                if callable(result):
+                    assert not helpers.is_coroutine_function(result), \
+                        'async functions are not supported in non-lazy demos'
+                    result()
 
     return f

website/documentation/intro.py

@@ -1,59 +1,105 @@
+import random
 from typing import Callable
 
 from nicegui import ui
 
 from ..style import subheading
+from .content.sub_pages_documentation import FakeSubPages
 from .demo import demo
 
 
 def create_intro() -> None:
-    @_main_page_demo('Styling', '''
-        While having reasonable defaults, you can still modify the look of your app with CSS as well as Tailwind and Quasar classes.
-    ''')
-    def formatting_demo():
-        ui.icon('thumb_up')
-        ui.markdown('This is **Markdown**.')
-        ui.html('This is <strong>HTML</strong>.', sanitize=False)
-        with ui.row():
-            ui.label('CSS').style('color: #888; font-weight: bold')
-            ui.label('Tailwind').classes('font-serif')
-            ui.label('Quasar').classes('q-ml-xl')
-        ui.link('NiceGUI on GitHub', 'https://github.com/zauberzeug/nicegui')
-
-    @_main_page_demo('Common UI Elements', '''
-        NiceGUI comes with a collection of commonly used UI elements.
+    @_main_page_demo('Single-Page Applications', '''
+        Build applications with fast client-side routing using [`ui.sub_pages`](/documentation/sub_pages)
+        and a `root` function as single entry point.
+        For each visitor, the `root` function is executed and generates the interface.
+        [`ui.link`](/documentation/link) and [`ui.navigate`](/documentation/navigate) can be used to navigate to other sub pages.
+
+        If you do not want a single-page application, you can also use [`@ui.page('/your/path')`](/documentation/page)
+        to define standalone content available at a specific path.
     ''')
-    def common_elements_demo():
-        from nicegui.events import ValueChangeEventArguments
-
-        def show(event: ValueChangeEventArguments):
-            name = type(event.sender).__name__
-            ui.notify(f'{name}: {event.value}')
-
-        ui.button('Button', on_click=lambda: ui.notify('Click'))
-        with ui.row():
-            ui.checkbox('Checkbox', on_change=show)
-            ui.switch('Switch', on_change=show)
-        ui.radio(['A', 'B', 'C'], value='A', on_change=show).props('inline')
-        with ui.row():
-            ui.input('Text input', on_change=show)
-            ui.select(['One', 'Two'], value='One', on_change=show)
-        ui.link('And many more...', '/documentation').classes('mt-8')
-
-    @_main_page_demo('Value Binding', '''
-        Binding values between UI elements and data models is built into NiceGUI.
+    def spa_demo():
+        sub_pages = None  # HIDE
+
+        def root():
+            # ui.sub_pages({
+            #     '/': table_page,
+            #     '/map/{lat}/{lon}': map_page,
+            # }).classes('w-full')
+            nonlocal sub_pages  # HIDE
+            sub_pages = FakeSubPages({'/': table_page, '/map/{lat}/{lon}': map_page}).classes('w-full')  # HIDE
+            sub_pages.init()  # HIDE
+
+        def table_page():
+            ui.table(rows=[
+                {'name': 'New York', 'lat': 40.7119, 'lon': -74.0027},
+                {'name': 'London', 'lat': 51.5074, 'lon': -0.1278},
+                {'name': 'Tokio', 'lat': 35.6863, 'lon': 139.7722},
+            ]).on('row-click', lambda e: sub_pages._render('/map/{lat}/{lon}', lat=e.args[1]['lat'], lon=e.args[1]['lon']))  # HIDE
+            # ]).on('row-click', lambda e: ui.navigate.to(f'/map/{e.args[1]["lat"]}/{e.args[1]["lon"]}'))
+
+        def map_page(lat: float, lon: float):
+            ui.leaflet(center=(lat, lon), zoom=10)
+            # ui.link('Back to table', '/')
+            sub_pages.link('Back to table', '/')  # HIDE
+
+        return root
+
+    @_main_page_demo('Reactive Transformations', '''
+        Create real-time interfaces with automatic updates.
+        Type and watch text flow in both directions.
+        When input changes, the [binding](/documentation/section_binding_properties) transforms the text
+        with a custom Python function and updates the label.
     ''')
     def binding_demo():
-        class Demo:
-            def __init__(self):
-                self.number = 1
-
-        demo = Demo()
-        v = ui.checkbox('visible', value=True)
-        with ui.column().bind_visibility_from(v, 'value'):
-            ui.slider(min=1, max=3).bind_value(demo, 'number')
-            ui.toggle({1: 'A', 2: 'B', 3: 'C'}).bind_value(demo, 'number')
-            ui.number().bind_value(demo, 'number')
+        def root():
+            user_input = ui.input(value='Hello')
+            ui.label().bind_text_from(user_input, 'value', reverse)
+
+        def reverse(text: str) -> str:
+            return text[::-1]
+
+        return root
+
+    @_main_page_demo('Event System', '''
+        Use an [Event](/documentation/event) to trigger actions and pass data.
+        Here we have an IoT temperature sensor submitting its readings
+        to a [FastAPI endpoint](/documentation/section_pages_routing#api_responses) with path "/sensor".
+        When a new value arrives, it emits an event for the chart to be updated.
+    ''')
+    def event_system_demo():
+        import time
+
+        from nicegui import Event, app
+
+        sensor = Event[float]()
+
+        # @app.post('/sensor')
+        def sensor_webhook(temperature: float):
+            sensor.emit(temperature)
+
+        def root():
+            chart = ui.echart({
+                'xAxis': {'type': 'time', 'axisLabel': {'hideOverlap': True}},
+                'yAxis': {'type': 'value', 'min': 'dataMin'},
+                'series': [{'type': 'line', 'data': [], 'smooth': True}],
+            })
+
+            def update_chart(temperature: float):
+                data = chart.options['series'][0]['data']
+                data.append([time.time(), temperature])
+                if len(data) > 10:
+                    data.pop(0)
+
+            sensor.subscribe(update_chart)
+            # END OF DEMO
+
+            data = chart.options['series'][0]['data']
+            data.append([time.time(), 24.0])
+            ui.timer(1.0, lambda: update_chart(round(data[-1][1] + (random.random() - 0.5), 1)), immediate=False)
+        app  # noqa: B018 to avoid unused import warning
+
+        return root
 
 
 def _main_page_demo(title: str, explanation: str) -> Callable:

website/main_page.py

@@ -121,13 +121,13 @@ def create() -> None:
                 'customizable [color themes](/documentation/section_styling_appearance#color_theming)',
                 'custom CSS and classes',
                 'modern look with material design',
-                '[Tailwind CSS](https://tailwindcss.com/) auto-completion',
+                '[Tailwind CSS](https://tailwindcss.com/)',
             ])
             features('source', 'Coding', [
-                'routing for multiple [pages](/documentation/page)',
+                'single page apps with [ui.sub_pages](/documentation/sub_pages)',
                 'auto-reload on code change',
                 'persistent [user sessions](/documentation/storage)',
-                'super nice [testing framework](/documentation/section_testing)',
+                'super powerful [testing framework](/documentation/section_testing)',
             ])
             features('anchor', 'Foundation', [
                 'generic [Vue](https://vuejs.org/) to Python bridge',