Custom component compiler callbacks (#29)

* Test cleanup

* Custom compiler callback support

* Update README.md

Author: JohnathonKoster

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [v1.4.0](https://github.com/Stillat/dagger/compare/v1.3.1...v1.4.0) - 2025-06-15
+
+- Adds the ability to compile components using a callback function
+
 ## [v1.3.1](https://github.com/Stillat/dagger/compare/v1.3.0...v1.3.1) - 2025-05-07
 
 - Corrects dependencies for Laravel 12 (#28)

README.md

@@ -79,6 +79,9 @@ The main visual difference when working with Dagger components is the use of the
   - [Disabling Compile Time Rendering on a Component](#disabling-compile-time-rendering-on-a-component)
   - [Enabling/Disabling Optimizations on Classes or Methods](#enablingdisabling-optimizations-on-classes-or-methods)
   - [Notes on Compile Time Rendering](#notes-on-compile-time-rendering)
+- [Component Compiler Callbacks](#component-compiler-callbacks)
+  - [Hanling Inner Content](#handling-inner-content)
+  - [Wildcard Component Patterns](#wildcard-component-patterns)
 - [The View Manifest](#the-view-manifest)
 - [License](#license)
 
@@ -1654,6 +1657,71 @@ class MyAwesomeClass
 - You should *never* attempt to force a component to render at compile time, outside of applying the `EnableOptimization` or `DisableOptimization` attributes to your own helper methods
 - If an exception is raised while rendering a component at compile time, CTR will be disabled for that component and the compiler will revert to normal behavior
 
+## Component Compiler Callbacks
+
+There are times you way wish to compile a component *without* a corresponding view file, similar to a directive. This can be accomplished by registering your custom component compiler callback using the `Compiler::compileComponent` method:
+
+```php
+<?php
+
+use Stillat\Dagger\Facades\Compiler;
+
+Compiler::compileComponent('c:mycomponent', function ($node) {
+    return 'My Component';
+});
+
+```
+
+Whenever the `<c-mycomponent />` component is compiled our custom callback will be invoked and that used as the compiled output.
+
+### Handling Inner Content
+
+For component tag pairs, the template compiler will provide the pre-compiled inner content as the second argument to the callback:
+
+```php
+<?php
+
+use Stillat\Dagger\Facades\Compiler;
+
+Compiler::compileComponent('c:mycomponent', function ($node, $innerContent) {
+    return '<div class="simple-wrapper">'.$innerContent.'</div>';
+});
+
+```
+
+This is useful if you would like to wrap the compiled output and not have to manage compiling the inner content yourself:
+
+```blade
+<c-mycomponent>
+    <x-alert title="Other Components" />
+</c-mycomponent>
+```
+
+### Wildcard Component Patterns
+
+You may use wildcards when registering your compiler callbacks:
+
+```php
+<?php
+
+use Illuminate\Support\Str;
+use Stillat\Dagger\Facades\Compiler;
+
+Compiler::compileComponent('c:stack:*', function ($node) {
+    $stackName = Str::after($node->tagName, ':');
+    
+    // ...
+});
+
+```
+
+Our callback would now be invoked for all of the following:
+
+```blade
+<s-stack:styles />
+<c-stack:scripts />
+```
+
 ## The View Manifest
 
 You may have noticed JSON files being written to your compiled view folder. These files are created by Dagger's "view manifest", which tracks dependencies of compiled views.

src/Compiler/Concerns/ManagesComponentCompilerCallbacks.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Stillat\Dagger\Compiler\Concerns;
+
+use Closure;
+use Illuminate\Support\Str;
+use Stillat\BladeParser\Nodes\Components\ComponentNode;
+use Stillat\Dagger\Exceptions\InvalidArgumentException;
+
+trait ManagesComponentCompilerCallbacks
+{
+    protected array $componentCompilers = [];
+
+    public function compileComponent(string $component, Closure $callback): static
+    {
+        $prefix = Str::before($component, ':');
+        $component = Str::after($component, ':');
+
+        if (! $prefix || ! in_array($prefix, $this->componentNamespaces)) {
+            throw new InvalidArgumentException("[$component] must have a registered component prefix.");
+        }
+
+        if (! $component) {
+            throw new InvalidArgumentException("[$component] is not a valid component name.");
+        }
+
+        return $this->compileComponentWithPrefix(
+            $prefix,
+            $component,
+            $callback
+        );
+    }
+
+    public function compileComponentWithPrefix(string $prefix, string $component, Closure $callback): static
+    {
+        if (! array_key_exists($prefix, $this->componentCompilers)) {
+            $this->componentCompilers[$prefix] = [];
+        }
+
+        $this->componentCompilers[$prefix][$component] = $callback;
+
+        return $this;
+    }
+
+    protected function compileComponentCallback(ComponentNode $node): mixed
+    {
+        if (! array_key_exists($node->componentPrefix, $this->componentCompilers)) {
+            return false;
+        }
+
+        /**
+         * @var $pattern
+         * @var Closure $callback
+         */
+        foreach ($this->componentCompilers[$node->componentPrefix] as $pattern => $callback) {
+            if (! Str::is($pattern, $node->tagName)) {
+                continue;
+            }
+
+            ray($pattern);
+
+            return $callback->call(
+                $this,
+                $node,
+                $this->compileNodes($node->childNodes ?? [])
+            );
+        }
+
+        return false;
+    }
+}

src/Compiler/TemplateCompiler.php

@@ -24,6 +24,7 @@
 use Stillat\Dagger\Compiler\Concerns\CompilesPhp;
 use Stillat\Dagger\Compiler\Concerns\CompilesSlots;
 use Stillat\Dagger\Compiler\Concerns\CompilesStencils;
+use Stillat\Dagger\Compiler\Concerns\ManagesComponentCompilerCallbacks;
 use Stillat\Dagger\Compiler\Concerns\ManagesComponentCtrState;
 use Stillat\Dagger\Compiler\Concerns\ManagesExceptions;
 use Stillat\Dagger\Exceptions\CompilerException;
@@ -54,6 +55,7 @@ final class TemplateCompiler
         CompilesPhp,
         CompilesSlots,
         CompilesStencils,
+        ManagesComponentCompilerCallbacks,
         ManagesComponentCtrState,
         ManagesExceptions;
 
@@ -401,6 +403,12 @@ protected function compileNodes(array $nodes): string
             $currentView = $this->manifest->last();
             $currentViewPath = $currentView?->getPath();
 
+            if ($callbackResult = $this->compileComponentCallback($node)) {
+                $compiled .= $callbackResult;
+
+                continue;
+            }
+
             if ($this->isDynamicComponent($node)) {
                 $compiled .= $this->compileDynamicComponentScaffolding($node, $currentViewPath ?? '');
 

src/Facades/Compiler.php

@@ -2,6 +2,7 @@
 
 namespace Stillat\Dagger\Facades;
 
+use Closure;
 use Illuminate\Support\Facades\Facade;
 use Stillat\Dagger\Compiler\CompilerOptions;
 use Stillat\Dagger\Compiler\TemplateCompiler;
@@ -11,6 +12,8 @@
  * @method static void addComponentPath(string $namespace, string $path)
  * @method static void registerComponentPath(string $componentPrefix, string $path, ?string $namespace = null)
  * @method static string compile(string $template)
+ * @method static TemplateCompiler compileComponent(string $component, Closure $callback)
+ * @method static TemplateCompiler compileComponentWithPrefix(string $prefix, string $component, Closure $callback)
  * @method static string compileWithLineNumbers(string $template)
  * @method static string getDynamicComponentPath(string $proxyName, string|null $componentName = null)
  * @method static bool compiledDynamicComponentExists(string $proxyName, string $componentName)

tests/AttributeCache/AttributeForwardingTest.php

@@ -1,9 +1,5 @@
 <?php
 
-use Stillat\Dagger\Tests\CompilerTestCase;
-
-uses(CompilerTestCase::class);
-
 test('forwarded attributes can be cached', function () {
     $template = <<<'BLADE'
 <c-cache.root #inner:title="The Title" />

tests/AttributeCache/DynamicComponentsAttributeForwardingTest.php

@@ -1,9 +1,5 @@
 <?php
 
-use Stillat\Dagger\Tests\CompilerTestCase;
-
-uses(CompilerTestCase::class);
-
 test('forwarded attributes can be cached inside dynamic components', function () {
     $template = <<<'BLADE'
 <c-dynamic-component component="cache.root" #inner:title="The Title" />

tests/AttributeCache/DynamicComponentsForwardedSlotsTest.php

@@ -1,9 +1,5 @@
 <?php
 
-use Stillat\Dagger\Tests\CompilerTestCase;
-
-uses(CompilerTestCase::class);
-
 test('forwarded named slots can be cached within dynamic components', function () {
     $template = <<<'BLADE'
 @for ($i = 0; $i < 3; $i++)

tests/AttributeCache/DynamicComponentsNamedSlotsTest.php

@@ -1,9 +1,5 @@
 <?php
 
-use Stillat\Dagger\Tests\CompilerTestCase;
-
-uses(CompilerTestCase::class);
-
 test('dynamic named slot variables bust the cache within dynamic components', function () {
     $template = <<<'BLADE'
 @for ($i = 0; $i < 2; $i++)

tests/AttributeCache/DynamicComponentsSlotsTest.php

@@ -1,9 +1,6 @@
 <?php
 
 use Illuminate\Support\Str;
-use Stillat\Dagger\Tests\CompilerTestCase;
-
-uses(CompilerTestCase::class);
 
 test('it replaces basic slot content within dynamic components', function () {
     $template = <<<'BLADE'