back + tests + doc

Author: dvlpp

demo/app/Sharp/Dashboard/DemoDashboard.php

@@ -135,6 +135,7 @@ protected function buildPageAlert(PageAlert $pageAlert): void
     {
         $pageAlert
             ->setLevelInfo()
+            ->onSection('stats-section')
             ->setMessage(
                 sprintf(
                     'Graphs below are delimited by period %s - %s (and yes, visits figures are randomly generated)',

demo/app/Sharp/Posts/PostShow.php

@@ -118,14 +118,13 @@ protected function buildPageAlert(PageAlert $pageAlert): void
     {
         $pageAlert
             ->setLevelInfo()
-            ->setMessage(function (array $data) {
-                return $data['publication']['is_planned']
-                    ? sprintf(
-                        'This post is planned for publication, on %s',
-                        $data['publication']['published_at'],
-                    )
-                    : null;
-            });
+            ->setMessage(fn (array $data) => $data['publication']['is_planned']
+                ? sprintf(
+                    'This post is planned for publication, on %s',
+                    $data['publication']['published_at'],
+                )
+                : null
+            );
     }
 
     public function getInstanceCommands(): ?array

docs/guide/page-alerts.md

@@ -91,3 +91,33 @@ class MyEntityList extends SharpEntityList
 }
 ```
 
+## Attach the page alert to a specific section (Show Page and Dashboard only)
+
+The `onSection()` method allows you to specify the section where the alert should be displayed (instead of the default, the top of the page):
+
+```php
+class MyShow extends SharpShow
+{
+    // ...
+    
+    protected function buildShowLayout(ShowLayout $showLayout): void
+    {
+        $showLayout
+            ->addSection(function (ShowLayoutSection $section) {
+                $section
+                    ->setKey('content')
+                    ->addColumn(/* ... */);
+            })
+            ->addSection(/* ... */);
+    }
+    
+    protected function buildPageAlert(PageAlert $pageAlert): void
+    {
+        $pageAlert
+            ->setMessage('This page has been edited recently.')
+            ->onSection('content');
+    }
+}
+```
+
+

src/Data/PageAlertData.php

@@ -12,6 +12,7 @@ final class PageAlertData extends Data
     public function __construct(
         public PageAlertLevel $level,
         public string $text,
+        public ?string $sectionKey = null,
         public ?string $buttonLabel = null,
         public ?string $buttonUrl = null,
     ) {}

src/Utils/PageAlerts/PageAlert.php

@@ -12,6 +12,7 @@ class PageAlert
     protected PageAlertLevel $pageAlertLevel = PageAlertLevel::Info;
     protected ?string $text;
     protected array $data;
+    protected ?string $sectionKey = null;
     protected ?string $buttonLabel = null;
     protected ?string $buttonUrl = null;
 
@@ -54,6 +55,13 @@ public function setLevelSecondary(): self
         return $this->setLevel(PageAlertLevel::Secondary);
     }
 
+    public function onSection(string $sectionKey): self
+    {
+        $this->sectionKey = $sectionKey;
+
+        return $this;
+    }
+
     public function setMessage(Closure|string $message): self
     {
         $this->text = $message instanceof Closure
@@ -77,6 +85,7 @@ final public function toArray(): ?array
             ? Arr::whereNotNull([
                 'level' => $this->pageAlertLevel,
                 'text' => $this->text,
+                'sectionKey' => $this->sectionKey,
                 'buttonLabel' => $this->buttonLabel,
                 'buttonUrl' => $this->buttonUrl,
             ])

tests/Http/ShowControllerTest.php

@@ -311,6 +311,33 @@ public function buildPageAlert(PageAlert $pageAlert): void
         );
 });
 
+it('allows to configure a page alert on a specific section', function () {
+    fakeShowFor('person', new class() extends PersonShow
+    {
+        public function buildPageAlert(PageAlert $pageAlert): void
+        {
+            $pageAlert
+                ->setLevelInfo()
+                ->onSection('my-section')
+                ->setMessage('My page alert')
+                ->setButton('My button', 'https://example.com');
+        }
+    });
+
+    $this->get('/sharp/s-list/person/s-show/person/1')
+        ->assertOk()
+        ->assertInertia(fn (Assert $page) => $page
+            ->where('show.pageAlert', [
+                'level' => PageAlertLevel::Info->value,
+                'text' => 'My page alert',
+                'sectionKey' => 'my-section',
+                'buttonLabel' => 'My button',
+                'buttonUrl' => 'https://example.com',
+            ])
+            ->etc()
+        );
+});
+
 it('allows to configure a page alert with a closure as content', function () {
     fakeShowFor('person', new class() extends PersonShow
     {