# TallStackUI: Dialog

> TallStackUI is a TALL Stack (Tailwind CSS, Alpine.js, Laravel, Livewire)
> component library providing 80+ Blade components for building modern web interfaces.

A modal dialog component for displaying alerts, confirmations, and question prompts with icon, title, description, and action buttons. Dispatched programmatically from Livewire components or controllers via the Interactions trait.

## Basic Usage

Place the component tag once in your layout file:

```blade
<x-dialog />
```

Dispatch from a Livewire component:

```php
use TallStackUi\Traits\Interactions;

class MyComponent extends Component
{
    use Interactions;

    public function save(): void
    {
        $this->dialog()->success('Saved!', 'Your record has been updated.')->send();
    }

    public function delete(int $id): void
    {
        $this->dialog()
            ->question('Delete Record?', 'This action cannot be undone.')
            ->confirm('Yes, delete', 'confirmDelete', $id)
            ->cancel('Cancel')
            ->send();
    }

    public function confirmDelete(int $id): void
    {
        // perform deletion
    }
}
```

Dispatch from a Controller (auto-flashes to session):

```php
use TallStackUi\Traits\Interactions;

class ItemController extends Controller
{
    use Interactions;

    public function destroy(Item $item): RedirectResponse
    {
        $item->delete();

        $this->dialog()->success('Deleted!', 'The item has been removed.')->send();

        return redirect()->back();
    }
}
```

## Interaction Methods

| Method     | Signature                                                                   | Description                                                   |
|------------|-----------------------------------------------------------------------------|---------------------------------------------------------------|
| success    | `success(string $title, ?string $description = null)`                       | Shows a success dialog with a check circle icon               |
| error      | `error(string $title, ?string $description = null)`                         | Shows an error dialog with an X circle icon                   |
| info       | `info(string $title, ?string $description = null)`                          | Shows an info dialog with an information circle icon          |
| warning    | `warning(string $title, ?string $description = null)`                       | Shows a warning dialog with an exclamation circle icon        |
| question   | `question(string $title, ?string $description = null)`                      | Shows a question dialog with a question mark circle icon      |
| confirm    | `confirm(?string $text, ?string $method, array\|string\|int\|null $params)` | Adds a confirm button that calls a Livewire method            |
| cancel     | `cancel(?string $text, ?string $method, array\|string\|int\|null $params)`  | Adds a cancel button that optionally calls a Livewire method  |
| persistent | `persistent()`                                                              | Prevents closing the dialog by clicking outside               |
| hook       | `hook(array $hooks)`                                                        | Registers lifecycle hooks (allowed: `ok`, `close`, `dismiss`) |
| flash      | `flash(bool $dispatch = false)`                                             | Flashes the interaction to session for display after redirect |
| send       | `send()`                                                                    | Dispatches the dialog                                         |

## Configuration

In `config/tallstackui.php` under `components.dialog`:

| Option     | Type   | Default | Description                                                |
|------------|--------|---------|------------------------------------------------------------|
| z-index    | string | 'z-50'  | Default z-index class                                      |
| overflow   | bool   | false   | When true, avoids hiding body overflow                     |
| blur       | bool   | false   | Enables background blur effect                             |
| persistent | bool   | false   | When true, prevents closing by clicking outside by default |

## Stacking

The dialog is teleported to the end of `<body>`, like the modal and the slide, and moves
to the last place there every time it opens. With the same `z-index`, the element that
comes last wins, so a dialog sent from inside an open modal or slide, nested modals
included, shows above it and takes the click, with the default configuration. A higher
`z-index` set on a modal still puts the modal above, since the class decides before the
order does.

Clicking outside the dialog only dismisses it when the click lands on its own backdrop.
A click on something shown above it, such as a toast that arrived while the dialog was
open, does not dismiss it.

The tag can also live inside a Livewire component instead of the layout: the teleported
dialog is kept across renders while open.

## Keyboard

The dialog is driven from the keyboard without any extra markup:

| Key      | Action                                                      | `persistent()` |
|----------|-------------------------------------------------------------|----------------|
| `Enter`  | Presses the confirm button (**OK**, or the `confirm()` one) | Works          |
| `Escape` | Dismisses the dialog, like clicking outside                 | Blocked        |

`Enter` closes a `success()`, `error()`, `info()` or `warning()` dialog and runs the
method of a `question()->confirm(...)`, matching a click on the button. It fires only
while the focus sits outside the dialog: a focused `<button>` already activates on
`Enter`, so the guard keeps a `Tab`-reached cancel button from cancelling and
confirming at once.

`Escape` is blocked by `persistent()`, and by `components.dialog.persistent` in the
config, because both exist to stop accidental dismissal. `Enter` is not: pressing the
confirm button is the answer the dialog is waiting for.

Both keys act only on the topmost overlay, so a dialog opened under a modal or slide
does not answer for the element above it.

## Confirm/Cancel Method Signatures

The `confirm()` and `cancel()` methods accept: text, method name, and params:

```php
public function save(): void
{
    $this->dialog()
        ->question('Warning!', 'Are you sure?')
        ->confirm('Confirm', 'confirmed', 'Confirmed Successfully')
        ->cancel('Cancel', 'cancelled', 'Cancelled Successfully')
        ->send();
}

public function confirmed(string $message): void
{
    $this->dialog()->success('Success', $message)->send();
}

public function cancelled(string $message): void
{
    $this->dialog()->error('Cancelled', $message)->send();
}
```

Both methods are optional. You can use only one, make them static (text only), or pass only method/params:

```php
// Static buttons (no method call)
->confirm('Confirm')
->cancel('Cancel')

// Named params only
->confirm(method: 'confirmed', params: 'data')
->cancel(method: 'cancelled', params: 'data')

// Confirmation with non-question types
$this->dialog()
    ->success('Done!', 'Process completed.')
    ->confirm('Undo', 'undo')
    ->cancel('Ok')
    ->send();
```

### Flash (Redirect Support)

Use `.flash()` to display after a redirect:

```php
$this->dialog()
    ->success('Done!', 'Your money has been sent!')
    ->flash()
    ->send();

return $this->redirect(route('dashboard'));
```

### Controller Usage

When using in Controllers, `confirm()` and `cancel()` are **not available** (no Livewire context). Only simple notifications work:

```php
use TallStackUi\Traits\Interactions;

class PaymentController extends Controller
{
    use Interactions;

    public function update(Request $request)
    {
        $this->dialog()->success('Updated!')->send();
    }
}
```

### Lifecycle Hooks

```php
$this->dialog()
    ->success('...')
    ->hook([
        'ok' => ['method' => 'onOk', 'params' => ['param1', 'param2']],
        'close' => ['method' => 'onClose', 'params' => ['param1']],
        'dismiss' => ['method' => 'onDismiss', 'params' => ['param1']],
    ])
    ->send();
```

Hook params can also be callables: `'params' => fn () => ['param1', 'param2']`

### Window Events

```blade
<div x-on:dialog:accepted.window="alert($event.detail.description)"
     x-on:dialog:rejected.window="alert($event.detail.description)"
     x-on:dialog:dismissed.window="alert($event.detail.description)">
    ...
</div>
```

## Soft Customization

Soft customization allows you to override default Tailwind CSS classes used by this component at runtime, either through a service provider or scoped per-instance.

### Customization

```php
TallStackUi::customize()
    ->dialog()
    ->block('background', 'your-tailwind-classes');
```

### Available Blocks

| Block Name               | Purpose                                     |
|--------------------------|---------------------------------------------|
| background               | Fixed overlay backdrop behind the dialog    |
| wrapper.first            | Fixed full-screen container                 |
| wrapper.second           | Centering flex container                    |
| wrapper.third            | Dialog card with rounded corners and shadow |
| icon.wrapper             | Circular icon background container          |
| icon.size                | Icon dimensions                             |
| text.wrapper             | Title and description container             |
| text.title               | Title heading styles                        |
| text.description.wrapper | Description text container                  |
| text.description.text    | Description paragraph styles                |
| buttons.wrapper          | Action buttons grid container               |
| buttons.confirm          | Confirm button styles                       |
| buttons.close.wrapper    | Close button container                      |
| buttons.close.icon       | Close X icon styles                         |