[WIP] Server Components

apps/dart_quotes/lib/main.client.options.dart

@@ -40,8 +40,8 @@ ClientOptions get defaultClientOptions => ClientOptions(
   clients: {
     'quote_like_button': ClientLoader(
       (p) => _quote_like_button.QuoteLikeButton(
-        id: p['id'] as String,
-        initialCount: p['initialCount'] as int,
+        id: p.get<String>('id'),
+        initialCount: p.get<int>('initialCount'),
       ),
       loader: _quote_like_button.loadLibrary,
     ),

apps/dart_quotes_server/lib/main.client.options.dart

@@ -29,8 +29,8 @@ ClientOptions get defaultClientOptions => ClientOptions(
   clients: {
     'quote_like_button': ClientLoader(
       (p) => _quote_like_button.QuoteLikeButton(
-        id: p['id'] as int,
-        initialCount: p['initialCount'] as int,
+        id: p.get<int>('id'),
+        initialCount: p.get<int>('initialCount'),
       ),
       loader: _quote_like_button.loadLibrary,
     ),

apps/fluttercon/lib/main.client.options.dart

@@ -38,7 +38,7 @@ ClientOptions get defaultClientOptions => ClientOptions(
   clients: {
     'like_button': ClientLoader(
       (p) => _like_button.LikeButton(
-        session: _session.SessionCodex.decode(p['session'] as String),
+        session: _session.SessionCodex.decode(p.get<String>('session')),
       ),
       loader: _like_button.loadLibrary,
     ),

apps/website/lib/main.client.options.dart

@@ -37,7 +37,7 @@ import 'package:website/pages/home/5_community/components/sponsors_list.dart'
 ClientOptions get defaultClientOptions => ClientOptions(
   clients: {
     'header': ClientLoader(
-      (p) => _header.Header(showHome: p['showHome'] as bool),
+      (p) => _header.Header(showHome: p.get<bool>('showHome')),
       loader: _header.loadLibrary,
     ),
     'install_command': ClientLoader(

apps/website/lib/pages/home/0_hero/components/meet_jaspr_button.dart

@@ -54,7 +54,7 @@ class MeetJasprButtonState extends State<MeetJasprButton> {
   Component build(BuildContext context) {
     if (notifier.done) {
       return div(id: 'meet-jaspr-button', [
-        .wrapElement(
+        .apply(
           events: {
             'click': (event) {
               event.preventDefault();
@@ -77,7 +77,7 @@ class MeetJasprButtonState extends State<MeetJasprButton> {
     }
 
     return div(id: 'meet-jaspr-button', [
-      .wrapElement(
+      .apply(
         classes: touchTimer != null ? 'active' : null,
         events: {
           'mousemove': (event) {

apps/website/lib/pages/home/2_devex/components/counter_button.dart

@@ -51,7 +51,7 @@ class CounterButtonState extends State<CounterButton> {
   Component build(BuildContext context) {
     return div(classes: 'counter-container', [
       Particles(particles: particles),
-      .wrapElement(
+      .apply(
         events: {
           'click': (event) {
             event.preventDefault();

docs.json

@@ -154,6 +154,10 @@
           "title": "💙 Flutter Embedding",
           "href": "/going_further/flutter_embedding"
         },
+        {
+          "title": "🖥️ Server Components",
+          "href": "/going_further/server_components"
+        },
         {
           "title": "🪐 Custom Backend",
           "href": "/going_further/backend"

docs/api/utils/at_client.mdx

@@ -102,6 +102,20 @@ Learn more about how to set up serialization for custom data types using the [`@
 
 With this setup you can use any class as the parameter of a `@client` component.
 
+### Server Components (Passing Components)
+
+Parameters can also be other components (type `Component`, including `List`s and `Map`s thereof). When you pass a component as a parameter to a `@client` component, it is treated as a **Server Component**:
+
+- It is rendered **only on the server**.
+- Its Dart code is **not** compiled to JavaScript and **never** executes on the client.
+- Its pre-rendered HTML structure is embedded directly into the `@client` component's output and is automatically mounted on the client during hydration.
+
+This is extremely useful when building layout components (like modals, sidebars, or tabs) that wrap large parts of your website that don't need client-side interactivity, thereby keeping your client bundle small.
+
+<Info>
+  For a detailed explanation of this design pattern, including advanced examples like Tab bars and component scope transitions, see the [Server Components Guide](/going_further/server_components).
+</Info>
+
 ## How it works
 
 The following happens when you use a `@client` component:
@@ -114,11 +128,10 @@ The following happens when you use a `@client` component:
 
 2. The component is built and pre-rendered normally.
 3. Jaspr adds a html marker (`<!--$<name> data=<serialized-parameters>-->`) around your components output.
-4. Jaspr adds the components js target as a `<script>` tag to the documents `<head>`.
 
 *on the client:*
 
-5. The browser loads the pre-rendered html and compiled js scripts.
-6. The used component is located based on the html marker.
-7. The parameters are deserialized and the component is mounted to the target element.
+4. The browser loads the pre-rendered html and compiled js scripts.
+5. The used component is located based on the html marker.
+6. The parameters are deserialized and the component is mounted to the target element.
 

docs/concepts/components.mdx

@@ -93,7 +93,7 @@ In every aspect, this component behaves the same as Flutter's `InheritedWidget`.
 
 ## Foundation Components
 
-Jaspr has three foundational component types, which are accessible through factory constructors on the `Component` class: `Component.element()`, `Component.text()` and `Component.fragment()`. Additionally, there are two more `Component.empty()` and `Component.wrapElement()` which are all explained below.
+Jaspr has three foundational component types, which are accessible through factory constructors on the `Component` class: `Component.element()`, `Component.text()` and `Component.fragment()`. Additionally, there are two more `Component.empty()` and `Component.apply()` which are all explained below.
 
 <Info>
 Unlike Flutter, Jaspr has a fixed number of foundational components which make up all other components and represent the core building blocks of HTML: element nodes and text nodes. Flutter is different because it allows you to write custom render objects with your own layouting and painting logic. This isn't possible in Jaspr because with HTML, the browser handles both layouting and painting. 
@@ -210,14 +210,14 @@ This is useful when you want to return "nothing" from a build method.
 final component = Component.empty();
 ```
 
-### Component.wrapElement()
+### Component.apply()
 
-A component which applies its attributes and parameters (like `classes`, `styles`,) etc.) to its direct child element(s).
+A component which applies its attributes and parameters (like `classes`, `styles`,) etc.) to its target element(s).
 
-This does not create a HTML element itself. All properties are merged with the respective child element's properties, with the child's properties taking precedence where there are conflicts.
+This does not create a HTML element itself. All properties are merged with the respective target element's properties, with the target's properties taking precedence where there are conflicts.
 
 ```dart
-final component = Component.wrapElement(
+final component = Component.apply(
   classes: 'wrapping-class',
   styles: Styles(backgroundColor: Colors.blue, padding: Padding.all(8.px)),
   child: div(
@@ -238,6 +238,28 @@ The above component renders the following HTML:
 </div>
 ```
 
+By default, `Component.apply()` targets all of its direct children. You can change this by using the `ApplyTarget target` parameter to target elements, either direct children or descendants, by tag, id or class names.
+
+```dart
+final component = Component.apply(
+  target: ApplyTarget.descendantWith(tag: 'p'),
+  styles: Styles(color: Colors.blue),
+  child: div([
+    p([
+      .text('Hello World'),
+    ]),
+  ]),
+);
+```
+
+The above component renders the following HTML:
+
+```html
+<div>
+  <p style="color: blue;">Hello World</p>
+</div>
+```
+
 ## Formatting Whitespace
 
 When pre-rendering your components in **server** and **static** mode, Jaspr will output cleanly formatted html on a best-effort basis. This means it will add newlines and indentations to your html element, while trying to not affect the way the html is rendered.