feat: add controls slot to callout component (#19263)

* Add support for callout control actions.

* Update documentation

* chore: fix code style

* cleanup

* screenshots

* better example

---------

Co-authored-by: gehrisandro <gehrisandro@users.noreply.github.com>
Co-authored-by: Dan Harrin <git@danharrin.com>

Author: gehrisandro

CLAUDE.md

@@ -242,7 +242,12 @@ Screenshots are in `docs-assets/screenshots/`. To add new screenshots:
    },
    ```
 
-3. **Generate screenshots**:
+3. **Build assets** if you changed any CSS or JS files (the docs app uses the compiled output):
+   ```bash
+   npm run build
+   ```
+
+4. **Generate screenshots**:
    ```bash
    # Terminal 1: Start the app server (must use default port 8000)
    cd docs-assets/app && php artisan serve
@@ -256,6 +261,6 @@ Screenshots are in `docs-assets/screenshots/`. To add new screenshots:
 
    **Important:** The script expects `http://127.0.0.1:8000`. Don't use a custom port.
 
-4. **Use in docs** with `<AutoScreenshot name="schemas/layout/my-component/simple" alt="Description" version="4.x" />`
+5. **Use in docs** with `<AutoScreenshot name="schemas/layout/my-component/simple" alt="Description" version="4.x" />`
 
 Screenshots are generated in `images/light/` and `images/dark/`. Use natural, realistic content - not test-like examples.

docs-assets/app/app/Livewire/Schemas/LayoutDemo.php

@@ -854,6 +854,22 @@ public function form(Schema $form): Schema
                                     ->button(),
                             ]),
                     ]),
+                Group::make()
+                    ->id('calloutControlActions')
+                    ->extraAttributes([
+                        'class' => 'p-16 max-w-2xl',
+                    ])
+                    ->schema([
+                        Callout::make('New version available')
+                            ->description('Filament v4 has been released with exciting new features and improvements.')
+                            ->info()
+                            ->controlActions([
+                                Action::make('dismiss')
+                                    ->icon(Heroicon::XMark)
+                                    ->iconButton()
+                                    ->color('gray'),
+                            ]),
+                    ]),
                 Group::make()
                     ->id('calloutActionsAlignedEnd')
                     ->extraAttributes([

docs-assets/screenshots/images/dark/schemas/layout/callout/control-actions.jpg

@@ -1808,6 +1808,15 @@ export default {
             deviceScaleFactor: 3,
         },
     },
+    'schemas/layout/callout/control-actions': {
+        url: 'schemas/layout',
+        selector: '#calloutControlActions',
+        viewport: {
+            width: 1920,
+            height: 320,
+            deviceScaleFactor: 3,
+        },
+    },
     'schemas/layout/callout/actions-aligned-end': {
         url: 'schemas/layout',
         selector: '#calloutActionsAlignedEnd',

docs-assets/screenshots/images/light/schemas/layout/callout/control-actions.jpg

@@ -213,6 +213,33 @@ You can also include buttons or other interactive elements in the footer:
 </x-filament::callout>
 ```
 
+## Adding content to the controls
+
+You can add custom content to the callout controls (top-right corner) using the `controls` slot:
+
+```blade
+<x-filament::callout
+    icon="heroicon-o-information-circle"
+    color="info"
+>
+    <x-slot name="heading">
+        Dismissible Callout
+    </x-slot>
+
+    <x-slot name="description">
+        This callout can be dismissed using the control in the top-right corner.
+    </x-slot>
+
+    <x-slot name="controls">
+        <x-filament::icon-button
+            icon="heroicon-m-x-mark"
+            color="gray"
+            label="Dismiss"
+        />
+    </x-slot>
+</x-filament::callout>
+```
+
 ## Callouts without an icon
 
 Callouts can be rendered without an icon if needed:

docs-assets/screenshots/schema.js

@@ -198,3 +198,48 @@ Callout::make('Backup complete')
 <UtilityInjection set="schemaComponents" version="4.x">As well as allowing a static value, the `footer()` method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>
 
 <AutoScreenshot name="schemas/layout/callout/footer" alt="Callout with custom footer content" version="4.x" />
+
+## Adding custom control content
+
+You can add custom content to the controls (top-right corner) using the `controls()` method. This accepts an array of schema components:
+
+```php
+use Filament\Actions\Action;
+use Filament\Schemas\Components\Callout;
+
+Callout::make('Backup complete')
+    ->description('Your data has been successfully backed up to the cloud.')
+    ->success()
+    ->controls([
+        Action::make('dismiss')
+            ->icon('heroicon-m-x-mark')
+            ->iconButton()
+            ->color('gray'),
+    ])
+```
+
+<UtilityInjection set="schemaComponents" version="4.x">As well as allowing a static value, the `controls()` method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.</UtilityInjection>
+
+## Adding control actions to the callout
+
+You can add control [actions](../actions) to the top-right corner of the callout using the `controlActions()` method. For example, you could add a dismiss button that hides the callout for the duration of the user's session:
+
+```php
+use Filament\Actions\Action;
+use Filament\Schemas\Components\Callout;
+use Filament\Support\Icons\Heroicon;
+
+Callout::make('New version available')
+    ->description('Filament v4 has been released with exciting new features and improvements.')
+    ->info()
+    ->controlActions([
+        Action::make('dismiss')
+            ->icon(Heroicon::XMark)
+            ->iconButton()
+            ->color('gray')
+            ->action(fn () => session()->put('new-version-callout-dismissed', true)),
+    ])
+    ->visible(fn (): bool => ! session()->get('new-version-callout-dismissed'))
+```
+
+<AutoScreenshot name="schemas/layout/callout/control-actions" alt="Callout with control actions" version="4.x" />

docs/12-components/03-callout.md

@@ -1,6 +1,7 @@
 @php
     use Filament\Support\Enums\IconSize;
 
+    $controls = $getChildSchema($schemaComponent::CONTROLS_SCHEMA_KEY)?->toHtmlString();
     $extraAttributeBag = $getExtraAttributeBag();
     $footer = $getChildSchema($schemaComponent::FOOTER_SCHEMA_KEY)?->toHtmlString();
     $color = $getColor();
@@ -26,4 +27,8 @@
     <x-slot name="footer">
         {{ $footer }}
     </x-slot>
+
+    <x-slot name="controls">
+        {{ $controls }}
+    </x-slot>
 </x-filament::callout>

packages/panels/dist/theme.css

@@ -20,6 +20,7 @@
 use Filament\Support\Facades\FilamentIcon;
 use Filament\Support\Icons\Heroicon;
 use Illuminate\Contracts\Support\Htmlable;
+use Illuminate\Support\Arr;
 
 class Callout extends Component
 {
@@ -45,10 +46,17 @@ class Callout extends Component
 
     public const FOOTER_SCHEMA_KEY = 'footer';
 
+    public const CONTROLS_SCHEMA_KEY = 'controls';
+
     protected bool $hasColor = false;
 
     protected string | Closure | null $status = null;
 
+    /**
+     * @var array<Action | Closure>
+     */
+    protected array $controlActions = [];
+
     final public function __construct(string | Htmlable | Closure | null $heading = null)
     {
         $this->heading($heading);
@@ -74,6 +82,10 @@ protected function setUp(): void
                 default => Schema::start($component->getFooterActions()),
             };
         });
+
+        $this->controls(function (Callout $component): Schema {
+            return Schema::start($component->getControlActions());
+        });
     }
 
     /**
@@ -179,6 +191,45 @@ public function getDefaultActions(): array
         return $this->getFooterActions();
     }
 
+    /**
+     * @param  array<Action | Closure>  $actions
+     */
+    public function controlActions(array $actions): static
+    {
+        $this->controlActions = [
+            ...$this->controlActions,
+            ...$actions,
+        ];
+
+        return $this;
+    }
+
+    /**
+     * @return array<Action>
+     */
+    public function getControlActions(): array
+    {
+        $actions = [];
+
+        foreach ($this->controlActions as $controlAction) {
+            foreach (Arr::wrap($this->evaluate($controlAction)) as $action) {
+                $actions[] = $this->prepareAction($action);
+            }
+        }
+
+        return $actions;
+    }
+
+    /**
+     * @param  array<Component | Action | ActionGroup | string | Htmlable> | Schema | Component | Action | ActionGroup | string | Htmlable | Closure | null  $components
+     */
+    public function controls(array | Schema | Component | Action | ActionGroup | string | Htmlable | Closure | null $components): static
+    {
+        $this->childComponents($components, static::CONTROLS_SCHEMA_KEY);
+
+        return $this;
+    }
+
     protected function configureChildSchema(Schema $schema, string $key): Schema
     {
         $schema = parent::configureChildSchema($schema, $key);
@@ -193,6 +244,15 @@ protected function configureChildSchema(Schema $schema, string $key): Schema
                 ->modifyActionGroupsUsing(fn (ActionGroup $actionGroup) => $actionGroup->defaultSize(Size::Small));
         }
 
+        if ($key === static::CONTROLS_SCHEMA_KEY) {
+            $schema
+                ->inline()
+                ->embeddedInParentComponent()
+                ->modifyActionsUsing(fn (Action $action) => $action
+                    ->defaultSize(Size::Small))
+                ->modifyActionGroupsUsing(fn (ActionGroup $actionGroup) => $actionGroup->defaultSize(Size::Small));
+        }
+
         return $schema;
     }
 }