Qute: add fragment named resolvers and capture alias for hidden fragment

- resolves #46355

Author: mkouba

docs/src/main/asciidoc/qute-reference.adoc

@@ -1258,8 +1258,8 @@ This is {#insert title}my title{/title}! <1>
 [[fragments]]
 ==== Fragments
 
-A fragment represents a part of the template that can be treated as a separate template, i.e. rendered separately.
-One of the main motivations to introduce this feature was to support use cases like https://htmx.org/essays/template-fragments/[htmx fragments].
+A fragment represents a part of a template that can be treated as a separate template, i.e. rendered separately.
+One of the main motivations to introduce this feature was the support of use cases like https://htmx.org/essays/template-fragments/[htmx fragments].
 
 Fragments can be defined with the `{#fragment}` section.
 Each fragment has an identifier that can only consist of alphanumeric characters and underscores.
@@ -1285,7 +1285,7 @@ NOTE: Note that a fragment identifier must be unique in a template.
 </ol>
 {/fragment}
 ----
-<1> Defines a fragment with identifier `item_aliases`. Note that only alphanumeric characters and underscores can be used in the identifier.
+<1> Defines a fragment with identifier `item_aliases`. Note that only alphanumeric characters and underscores can be used in the identifier. The name of the first parameter can be omitted - `{#fragment item_aliases}` is fine too. 
 
 You can obtain a fragment programmatically via the `io.quarkus.qute.Template.getFragment(String)` method.
 
@@ -1318,49 +1318,63 @@ The snippet above should render something like:
 TIP: In Quarkus, it is also possible to define a <<type_safe_fragments,type-safe fragment>>.
 
 You can also include a fragment with an `{#include}` section inside another template or the template that defines the fragment.
+A fragment can be also used in expressions with the `frg:`/`fragment:` namespaces.
 
 .Including a Fragment in `user.html`
 [source,html]
 ----
 <h1>User - {user.name}</h1>
 
+<p>
+{#fragment fullname}
+{name} <strong>{surname}</strong>
+{/fragment}
+</p>
+
 <p>This document contains a detailed info about a user.</p>
 
 {#include item$item_aliases aliases=user.aliases /} <1><2>
+
+{frg:fullname} is a happy user! <3>
 ----
 <1> A template identifier that contains a dollar sign `$` denotes a fragment. The `item$item_aliases` value is translated as: _Use the fragment `item_aliases` from the template `item`._
 <2> The `aliases` parameter is used to pass the relevant data. We need to make sure that the data are set correctly. In this particular case the fragment will use the expression `user.aliases` as the value of `aliases` in the `{#for alias in aliases}` section.
+<3> The `{frg:username}` expression outputs the fragment content. `frg:` can be replaced with `fragment:`.
 
 TIP: If you want to reference a fragment from the same template, skip the part before `$`, i.e. something like `{#include $item_aliases /}`.
 
 NOTE: You can specify `{#include item$item_aliases _ignoreFragments=true /}` in order to disable this feature, i.e. a dollar sign `$` in the template identifier does not result in a fragment lookup.
 
-===== Hidden Fragments
+
+===== Hidden Fragments (Capture)
 
 By default, a fragment is normally rendered as a part of the original template.
-However, sometimes it might be useful to mark a fragment as _hidden_ with `rendered=false`.
-An interesting use case would be a fragment that can be used multiple-times inside the template that defines it.
+However, sometimes it might be useful to mark a fragment as _hidden_.
+The regular fragment section has the `capture` alias that implies a hidden fragment.
+Alternatively, you can "hide" a fragment either with `rendered=false` or `_hidden` parameters.
+An interesting use case could be a fragment that can be used multiple-times inside the template that defines it.
 
-.Fragment Definition in `item.html`
+.Hidden Fragment Definition in `item.html`
 [source,html]
 ----
-{#fragment id=strong rendered=false} <1>
+{#capture strong} <1>
 <strong>{val}</strong>
-{/fragment}
+{/capture}
 
 <h1>My page</h1>
 <p>This document
 {#include $strong val='contains' /} <2>
 a lot of
-{#include $strong val='information' /} <3>
+{capture:strong(param:val = 'information')} <3> <4>
 !</p>
 ----
 <1> Defines a hidden fragment with identifier `strong`.
-In this particular case, we use the `false` boolean literal as the value of the `rendered` parameter.
-However, it's possible to use any expression there.
+`{#capture strong}` can be replaced with `{#fragment strong rendered=false}` or `{#fragment strong _hidden}`.
+The `rendered` parameter can use any expression, e.g. `{#fragment strong rendered=config.isRendered}`.
 <2> Include the fragment `strong` and pass the value.
 Note the syntax `$strong` which is translated to include the fragment `strong` from the current template.
-<3> Include the fragment `strong` and pass the value.
+<3> A namespace resolver can be used to access a hidden fragment too. `capture:` can be replaced with `cap:`.
+<4> `param:val = 'information'` is used to pass a named parameter to the fragment. 
 
 The snippet above renders something like:
 
@@ -1374,6 +1388,8 @@ a lot of
 !</p>
 ----
 
+TIP: In Quarkus, the namespace resolvers are automatically registered for namespaces `frg`, `fragment`, `cap` and `capture`.
+
 ==== Eval Section
 
 This section can be used to parse and evaluate a template dynamically.

extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/fragment/HiddenFragmentsTest.java

@@ -0,0 +1,50 @@
+package io.quarkus.qute.deployment.fragment;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+
+import org.jboss.shrinkwrap.api.asset.StringAsset;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.qute.Template;
+import io.quarkus.test.QuarkusUnitTest;
+
+public class HiddenFragmentsTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withApplicationRoot(root -> root
+                    .addAsResource(new StringAsset("""
+                            {#capture faClass}
+                            {#when type}
+                              {#is "info"}
+                                fa fa-lightbulb
+                              {#is "warning"}
+                                fa fa-exclamation-triangle
+                              {#is "error"}
+                                fa fa-times-circle
+                              {#is "success"}
+                                fa fa-check-circle
+                              {#is "question"}
+                                fa fa-question-circle
+                              {#else}
+                                fa fa-info-circle
+                              {/when}
+                            {/}
+                            <i class="{capture:faClass(param:type = type.or(anotherType)).strip}"></i>::{capture:faClass.strip}
+                                                        """), "templates/hide.html"));
+
+    @Inject
+    Template hide;
+
+    @Test
+    public void testResolvers() {
+        assertEquals("<i class=\"fa fa-times-circle\"></i>::fa fa-times-circle",
+                hide.data("type", "error", "anotherType", "foo").render().strip());
+        assertEquals("<i class=\"fa fa-question-circle\"></i>::fa fa-info-circle",
+                hide.data("type", null, "anotherType", "question").render().strip());
+    }
+
+}

extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/EngineProducer.java

@@ -20,6 +20,14 @@
 import java.util.concurrent.ConcurrentMap;
 import java.util.regex.Pattern;
 
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.context.Dependent;
+import jakarta.enterprise.event.Event;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.inject.Produces;
+import jakarta.inject.Singleton;
+import jakarta.interceptor.Interceptor;
+
 import org.jboss.logging.Logger;
 
 import io.quarkus.arc.All;
@@ -35,6 +43,7 @@
 import io.quarkus.qute.HtmlEscaper;
 import io.quarkus.qute.ImmutableList;
 import io.quarkus.qute.JsonEscaper;
+import io.quarkus.qute.NamedArgument;
 import io.quarkus.qute.NamespaceResolver;
 import io.quarkus.qute.ParserHook;
 import io.quarkus.qute.Qute;
@@ -58,13 +67,6 @@
 import io.quarkus.runtime.LocalesBuildTimeConfig;
 import io.quarkus.runtime.ShutdownEvent;
 import io.quarkus.runtime.Startup;
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.enterprise.context.Dependent;
-import jakarta.enterprise.event.Event;
-import jakarta.enterprise.event.Observes;
-import jakarta.enterprise.inject.Produces;
-import jakarta.inject.Singleton;
-import jakarta.interceptor.Interceptor;
 
 @Startup(Interceptor.Priority.PLATFORM_BEFORE)
 @Singleton
@@ -129,6 +131,8 @@ public EngineProducer(QuteContext context, QuteConfig config, QuteRuntimeConfig
         builder.addValueResolver(ValueResolvers.orEmpty());
         // Note that arrays are handled specifically during validation
         builder.addValueResolver(ValueResolvers.arrayResolver());
+        // Named arguments for fragment namespace resolver
+        builder.addValueResolver(new NamedArgument.SetValueResolver());
         // Additional value resolvers
         for (ValueResolver valueResolver : valueResolvers) {
             builder.addValueResolver(valueResolver);
@@ -197,6 +201,12 @@ public EngineProducer(QuteContext context, QuteConfig config, QuteRuntimeConfig
         }
         // str:eval
         builder.addNamespaceResolver(new StrEvalNamespaceResolver());
+        // Fragment namespace resolvers
+        builder.addNamespaceResolver(new NamedArgument.ParamNamespaceResolver());
+        builder.addNamespaceResolver(new FragmentNamespaceResolver(FragmentNamespaceResolver.FRAGMENT));
+        builder.addNamespaceResolver(new FragmentNamespaceResolver(FragmentNamespaceResolver.FRG));
+        builder.addNamespaceResolver(new FragmentNamespaceResolver(FragmentNamespaceResolver.CAPTURE));
+        builder.addNamespaceResolver(new FragmentNamespaceResolver(FragmentNamespaceResolver.CAP));
 
         // Add generated resolvers
         for (String resolverClass : context.getResolverClasses()) {

extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/TemplateProducer.java

@@ -34,6 +34,7 @@
 import io.quarkus.qute.ParameterDeclaration;
 import io.quarkus.qute.RenderedResults;
 import io.quarkus.qute.ResultsCollectingTemplateInstance;
+import io.quarkus.qute.SectionNode;
 import io.quarkus.qute.Template;
 import io.quarkus.qute.TemplateInstance;
 import io.quarkus.qute.TemplateInstanceBase;
@@ -172,6 +173,14 @@ public Template get() {
             this.renderedResults = renderedResults;
         }
 
+        @Override
+        public SectionNode getRootNode() {
+            if (unambiguousTemplate != null) {
+                return unambiguousTemplate.get().getRootNode();
+            }
+            throw ambiguousTemplates("getRootNode()");
+        }
+
         @Override
         public TemplateInstance instance() {
             TemplateInstance instance = new InjectableTemplateInstanceImpl();
@@ -322,6 +331,11 @@ public List<TemplateNode> getNodes() {
                 return InjectableTemplate.this.getNodes();
             }
 
+            @Override
+            public SectionNode getRootNode() {
+                return InjectableTemplate.this.getRootNode();
+            }
+
             @Override
             public Collection<TemplateNode> findNodes(Predicate<TemplateNode> predicate) {
                 return InjectableTemplate.this.findNodes(predicate);

independent-projects/qute/core/src/main/java/io/quarkus/qute/EvalSectionHelper.java

@@ -55,10 +55,10 @@ public CompletionStage<ResultNode> resolve(SectionResolutionContext context) {
     }
 
     private void parseAndResolve(CompletableFuture<ResultNode> ret, String contents, ResolutionContext resolutionContext) {
-        TemplateImpl template;
+        Template template;
         try {
-            template = (TemplateImpl) engine.parse(contents);
-            template.root
+            template = engine.parse(contents);
+            template.getRootNode()
                     .resolve(resolutionContext)
                     .whenComplete((resultNode, t2) -> {
                         if (t2 != null) {

independent-projects/qute/core/src/main/java/io/quarkus/qute/FragmentNamespaceResolver.java

@@ -0,0 +1,133 @@
+package io.quarkus.qute;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.ExecutionException;
+
+import io.quarkus.qute.EngineBuilder.EngineListener;
+import io.quarkus.qute.Template.Fragment;
+
+/**
+ * Renders a matching fragment from the current template.
+ *
+ * @see FragmentSectionHelper
+ */
+public class FragmentNamespaceResolver implements NamespaceResolver, EngineListener {
+
+    public static final String FRG = "frg";
+    public static final String FRAGMENT = "fragment";
+    public static final String CAP = "cap";
+    public static final String CAPTURE = "capture";
+
+    private final String namespace;
+
+    private final int priority;
+
+    private volatile Engine engine;
+
+    public FragmentNamespaceResolver() {
+        this(FRG, -1);
+    }
+
+    public FragmentNamespaceResolver(String namespace) {
+        this(namespace, -1);
+    }
+
+    public FragmentNamespaceResolver(String namespace, int priority) {
+        this.namespace = namespace;
+        this.priority = priority;
+    }
+
+    @Override
+    public void engineBuilt(Engine engine) {
+        this.engine = engine;
+    }
+
+    @Override
+    public CompletionStage<Object> resolve(EvalContext context) {
+        String id = context.getName();
+        Template template = null;
+        int idx = id.lastIndexOf('$');
+        if (idx != -1) {
+            // the part before the last occurence of a dollar sign is the template identifier
+            String templateId = id.substring(0, idx);
+            Engine e = engine;
+            if (e == null) {
+                throw new TemplateException("Engine not set");
+            }
+            template = e.getTemplate(templateId);
+            if (template == null) {
+                throw new TemplateException("Template not found: " + templateId);
+            }
+            // the part after the last occurence of a dollar sign is the fragment identifier
+            id = id.substring(idx + 1);
+        } else {
+            template = context.resolutionContext().getTemplate();
+        }
+        Fragment fragment = template.getFragment(id);
+        if (fragment != null) {
+            CompletableFuture<Object> ret = new CompletableFuture<>();
+            if (!context.getParams().isEmpty()) {
+                EvaluatedParams params = EvaluatedParams.evaluate(context);
+                params.stage.whenComplete((r, t) -> {
+                    if (t != null) {
+                        ret.completeExceptionally(t);
+                    } else {
+                        Map<String, Object> args = new HashMap<>();
+                        for (int i = 0; i < context.getParams().size(); i++) {
+                            try {
+                                Object result = params.getResult(i);
+                                if (result instanceof NamedArgument arg) {
+                                    args.put(arg.getName(), arg.getValue());
+                                } else {
+                                    ret.completeExceptionally(
+                                            new TemplateException("Named argument expected: " + result.getClass()));
+                                    break;
+                                }
+                            } catch (InterruptedException | ExecutionException e) {
+                                ret.completeExceptionally(e);
+                            }
+                        }
+                        ResolutionContext child = context.resolutionContext().createChild(Mapper.wrap(args), null);
+                        fragment.getRootNode().resolve(child, Map.of(Template.Fragment.ATTRIBUTE, true))
+                                .whenComplete((r2, t2) -> {
+                                    if (t2 != null) {
+                                        ret.completeExceptionally(t2);
+                                    } else {
+                                        StringBuilder sb = new StringBuilder();
+                                        r2.process(sb::append);
+                                        ret.complete(sb.toString());
+                                    }
+                                });
+                    }
+                });
+            } else {
+                fragment.getRootNode().resolve(context.resolutionContext(), Map.of(Template.Fragment.ATTRIBUTE, true))
+                        .whenComplete((r, t) -> {
+                            if (t != null) {
+                                ret.completeExceptionally(t);
+                            } else {
+                                StringBuilder sb = new StringBuilder();
+                                r.process(sb::append);
+                                ret.complete(sb.toString());
+                            }
+                        });
+            }
+            return ret;
+        }
+        return Results.notFound(context);
+    }
+
+    @Override
+    public int getPriority() {
+        return priority;
+    }
+
+    @Override
+    public String getNamespace() {
+        return namespace;
+    }
+
+}