Merge pull request #14782 from filamentphp/stats-overview-heading-desc

Widgets/StatsOverview: Add support for heading and description

packages/widgets/docs/02-stats-overview.md

@@ -165,3 +165,27 @@ To disable this behavior, you may override the `$isLazy` property on the widget
 ```php
 protected static bool $isLazy = false;
 ```
+
+## Adding a header and description
+
+You may also add a header and description text above the widget by overriding the `$header` and `$description` properties:
+
+```php
+protected ?string $header = 'Analytics';
+
+protected ?string $description = 'An overview of some analytics.';
+```
+
+If you need to dynamically generated the header or description text, you can instead override the `getHeader()` and `getDescription()` methods:
+
+```php
+protected function getHeader(): ?string
+{
+    return 'Analytics';
+}
+
+protected function getDescription(): ?string
+{
+    return 'An overview of some analytics.';
+}
+```

packages/widgets/resources/views/stats-overview-widget.blade.php

@@ -1,8 +1,32 @@
 @php
     $columns = $this->getColumns();
+    $heading = $this->getHeading();
+    $description = $this->getDescription();
+    $hasHeading = filled($heading);
+    $hasDescription = filled($description);
 @endphp
 
-<x-filament-widgets::widget class="fi-wi-stats-overview">
+<x-filament-widgets::widget class="fi-wi-stats-overview grid gap-y-4">
+    @if ($hasHeading || $hasDescription)
+        <div class="fi-wi-stats-overview-header grid gap-y-1">
+            @if ($hasHeading)
+                <h3
+                    class="fi-wi-stats-overview-header-heading col-span-full text-base font-semibold leading-6 text-gray-950 dark:text-white"
+                >
+                    {{ $heading }}
+                </h3>
+            @endif
+
+            @if ($hasDescription)
+                <p
+                    class="fi-wi-stats-overview-header-description overflow-hidden break-words text-sm text-gray-500 dark:text-gray-400"
+                >
+                    {{ $description }}
+                </p>
+            @endif
+        </div>
+    @endif
+
     <div
         @if ($pollingInterval = $this->getPollingInterval())
             wire:poll.{{ $pollingInterval }}

packages/widgets/src/StatsOverviewWidget.php

@@ -15,6 +15,10 @@ class StatsOverviewWidget extends Widget
 
     protected int | string | array $columnSpan = 'full';
 
+    protected ?string $heading = null;
+
+    protected ?string $description = null;
+
     /**
      * @var view-string
      */
@@ -53,6 +57,16 @@ class StatsOverviewWidget extends Widget
         return [];
     }
 
+    protected function getDescription(): ?string
+    {
+        return $this->description;
+    }
+
+    protected function getHeading(): ?string
+    {
+        return $this->heading;
+    }
+
     /**
      * @return array<Stat>
      */