From c0077bf27f252a2f2d9056f0d8a0e3b0b0dd43e4 Mon Sep 17 00:00:00 2001
From: Adam Weston <adam@awcodes.com>
Date: Wed, 3 Jun 2026 16:04:57 -0400
Subject: [PATCH] implement tags feature

---
 README.md                                      | 18 ++++++++++++++++++
 .../components/brick-picker-modal.blade.php    | 14 +++++++++-----
 resources/views/components/sidebar.blade.php   | 14 +++++++++-----
 src/Brick.php                                  |  8 ++++++++
 tests/src/BrickTest.php                        | 10 ++++++++++
 tests/src/Fixtures/TestBrick.php               |  5 +++++
 6 files changed, 59 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 30ad3ac..19fd813 100644
--- a/README.md
+++ b/README.md
@@ -379,6 +379,11 @@ class Section extends Brick
         return new HtmlString('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 20h.01M4 20h.01M8 20h.01M12 20h.01M16 20h.01M20 4h.01M4 4h.01M8 4h.01M12 4h.01M16 4v.01M4 9a1 1 0 0 1 1-1h14a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1z"/></svg>');
     }
 
+    public static function getTags(): array
+    {
+        return ['section', 'content', 'layout'];
+    }
+
     /**
      * @throws Throwable
      */
@@ -404,6 +409,19 @@ class Section extends Brick
 }
 ```
 
+### Brick Tags
+
+Bricks can optionally declare tags to improve discoverability when searching the editor sidebar. When a user types in the search box, Mason will match against both the brick's label and any of its tags, so a search for "marketing" can surface a brick whose label is "Hero" as long as that tag is defined.
+
+```php
+public static function getTags(): array
+{
+    return ['hero', 'banner', 'header', 'landing page', 'marketing'];
+}
+```
+
+By default, `getTags()` returns an empty array, so tags are entirely optional.
+
 ## Rendering Content
 
 You are free to render the content however you see fit. The data is stored in the database as JSON, so you can use the data however you see fit. But the plugin offers a helper method for converting the data to HTML should you choose to use it.
diff --git a/resources/views/components/brick-picker-modal.blade.php b/resources/views/components/brick-picker-modal.blade.php
index 61e9181..e87ba75 100644
--- a/resources/views/components/brick-picker-modal.blade.php
+++ b/resources/views/components/brick-picker-modal.blade.php
@@ -3,7 +3,7 @@
 ])
 
 @php
-    $brickIds = array_map(fn ($brick) => $brick::getLabel(), $bricks);
+    $brickData = array_map(fn ($brick) => ['label' => $brick::getLabel(), 'tags' => $brick::getTags()], $bricks);
 @endphp
 
 <div
@@ -29,12 +29,16 @@ class="mason-brick-picker-overlay"
         x-transition:leave-end="scale-95 opacity-0"
         class="mason-brick-picker-modal"
         x-data="{
-            actions: @js($brickIds),
+            actions: @js($brickData),
             search: '',
             filterActions: function () {
-                return this.actions.filter((name) =>
-                    name.toLowerCase().includes(this.search.toLowerCase()),
-                )
+                const q = this.search.toLowerCase()
+                return this.actions
+                    .filter((brick) =>
+                        brick.label.toLowerCase().includes(q) ||
+                        brick.tags.some((tag) => tag.toLowerCase().includes(q)),
+                    )
+                    .map((brick) => brick.label)
             },
         }"
     >
diff --git a/resources/views/components/sidebar.blade.php b/resources/views/components/sidebar.blade.php
index f80d145..8856c3d 100644
--- a/resources/views/components/sidebar.blade.php
+++ b/resources/views/components/sidebar.blade.php
@@ -5,7 +5,7 @@
 ])
 
 @php
-    $brickIds = array_map(fn ($brick) => $brick::getLabel(), $bricks);
+    $brickData = array_map(fn ($brick) => ['label' => $brick::getLabel(), 'tags' => $brick::getTags()], $bricks);
 @endphp
 
 <div
@@ -21,12 +21,16 @@
         class="mason-actions"
         wire:ignore
         x-data="{
-            actions: @js($brickIds),
+            actions: @js($brickData),
             search: '',
             filterActions: function () {
-                return this.actions.filter((name) =>
-                    name.toLowerCase().includes(this.search.toLowerCase()),
-                )
+                const q = this.search.toLowerCase()
+                return this.actions
+                    .filter((brick) =>
+                        brick.label.toLowerCase().includes(q) ||
+                        brick.tags.some((tag) => tag.toLowerCase().includes(q)),
+                    )
+                    .map((brick) => brick.label)
             },
         }"
     >
diff --git a/src/Brick.php b/src/Brick.php
index 84f6644..dbfc9b1 100644
--- a/src/Brick.php
+++ b/src/Brick.php
@@ -25,6 +25,14 @@ public static function getIcon(): string | Heroicon | Htmlable | null
         return null;
     }
 
+    /**
+     * @return array<string>
+     */
+    public static function getTags(): array
+    {
+        return [];
+    }
+
     public static function toHtml(array $config, ?array $data = null): ?string
     {
         return null;
diff --git a/tests/src/BrickTest.php b/tests/src/BrickTest.php
index df57431..d804b78 100644
--- a/tests/src/BrickTest.php
+++ b/tests/src/BrickTest.php
@@ -34,6 +34,16 @@
         });
     });
 
+    describe('getTags()', function () {
+        it('returns defined tags', function () {
+            expect(TestBrick::getTags())->toBe(['hero', 'banner', 'marketing']);
+        });
+
+        it('returns empty array when not overridden', function () {
+            expect(SimpleBrick::getTags())->toBe([]);
+        });
+    });
+
     describe('toHtml()', function () {
         it('renders HTML with config', function () {
             $html = TestBrick::toHtml(['title' => 'My Title', 'content' => 'My Content']);
diff --git a/tests/src/Fixtures/TestBrick.php b/tests/src/Fixtures/TestBrick.php
index c311f84..8df7589 100644
--- a/tests/src/Fixtures/TestBrick.php
+++ b/tests/src/Fixtures/TestBrick.php
@@ -20,6 +20,11 @@ public static function getIcon(): ?string
         return 'heroicon-o-star';
     }
 
+    public static function getTags(): array
+    {
+        return ['hero', 'banner', 'marketing'];
+    }
+
     public static function toHtml(array $config, ?array $data = null): ?string
     {
         $title = $config['title'] ?? '';