Replace intro demos with more educational code/text

[rodja]

Motivation

The main page demos are often the first code examples new users see. The previous demos (Styling, Common UI Elements, and Value Binding) showed what was possible but didn't effectively communicate NiceGUI's new core paradigm: building SPAs with a root function as the single entry point. This is a fundamental pattern that users should grasp early, especially those transitioning from frameworks like Streamlit.
The old demos also introduced too many concepts at once without clear educational flow, making it harder for newcomers to form the right mental model.

Implementation

• replace old intro-demos with two new demos (single page app & reactive transformations). I would have liked a third one which demonstrates global state but had no good idea yet. So I'll leave it for another PR.
• changed @ui.page decorator in feature list with ui.sub_pages to establish SPA as the primary pattern.
• some improved infrastructure
  • by returning root the @demo helper automatically executes the root function and replaces the code to display with ui.run(root) (it is not used everywhere yet to minimize diff of this PR and reduce collisions with ideas from introduce code transformation to simplify writing ui.sub_pages demos #5274)
  • made FakeSubPages.link() return ui.label to enable method chaining

Progress

• I chose a meaningful title that completes the sentence: "If applied, this PR will..."
• The implementation is complete.
• Pytests are not necessary.
• Documentation has been updated.

[evnchn]

Generally a good idea to re-work the docs. I wish we did it in 3.0 release but we are stretched back then.

Importantly, I don't think we can put sub-pages at the spotlight while the API is still warned to be subject-to-change in the documentations. It may give a bad impression.

Recommended course of action:

1. Mark the sub-pages API as stable, then we can spotlight it.
2. If not we will have to put @ui.page first and sub-pages second.
3. Or it may be good to show both (maybe even alongside each other in 2 demos) considering there may be users coming from FastAPI / Flask, which uses decorators.

While we're at it can we also spotlight the new Event system? Phrase "Once part of RoSys, our robot system built on top of NiceGUI, the Event system ..." can help you plug a RoSys link as well.

[rodja]

Importantly, I don't think we can put sub-pages at the spotlight while the API is still warned to be subject-to-change in the documentations.

You are right. I just talked to @falkoschindler and we agreed to remove the warning. It's about time!

[rodja]

While we're at it can we also spotlight the new Event system?

Yes, I would really like that. But such a demo is blocked by #5231. Otherwise opening two tabs will have a high chance of not seeing the triggered events (because you land on another instance). Let's leave it for another PR.

[evnchn]

... spotlight the new Event system ... blocked by #5231

If the source of the events are not triggerable by user but come from hypothetical sources, we can easily get away with it.

Imagine a demo:

from nicegui import ui, app, Event

temperature_event = Event[int]()

@app.get('/temperature_sensor')
def temperature_sensor_webhook(temperature: float):
    temperature_event.emit(temperature)

@ui.page('/')
def temperature_dashboard():
    # some logic to subscribe to the temperature_event

We won't really expose /temperature_sensor in reality, though.

And then we mock the demo with fluctuating temperatures from 24 to 26 degree celsius.

[rodja]

If the source of the events are not triggerable by user but come from hypothetical sources, we can easily get away with it.

Great idea. I also like that it would demonstrate the integration with FastAPI RESTful APIs!

[evnchn]

8fcfbad

Did not wound up adding a link to RoSys since the rest of the demo text is so short.

[rodja]

Thanks @evnchn. I replaced the log with an echart to squeeze in some data visualization. Even if the demo is a bit longer that way, I think its worth it.

[evnchn]

more "wow"

A good idea in general because some of the examples are too simple, really.

Going forward I envision a "level select" for any demo's technical depth, possibly from "basic", "advanced" to "expert".

See if that's considerable. If so can go to NiceGUI Wishlist (may need designer's help to elegantly put a selector in the existing demo)

[rodja]

Going forward I envision a "level select" for any demo's technical depth, possibly from "basic", "advanced" to "expert".

I'm not sure if that is a good idea. It would add quite a bit of complexity. I think the intro-demos should be a a mix of 33% "nice", 33% "wow" and 33% "aha". We have the in-depth examples for advanced and expert users.

[falkoschindler]

As discussed with @rodja, I filled the SPA with a ui.table and a ui.leaflet map to make it visually more interesting. At the same time I tried to keep the code short and simple. The generic "row-click" event is a bit tricky, but I think it's good enough for now.

Let's merge this and further improve on a separate PR.