Empty State

Obrazovka, kterou uživatel potká dřív, než cokoli vytvoří. EmptyState je vycentrovaná ikona, nadpis, věta a — to podstatné — tlačítka, která ho z toho dostanou. Sáhni po něm všude, kde seznam legitimně může být prázdný, a řekni, co dělat dál, ne jenom to, že tu nic není.

use NyonCode\WireCore\Foundation\Schema\EmptyState;

Jak to funguje

Empty state je layoutová komponenta: žádná hodnota, žádná state path. Vykreslí jeden vycentrovaný sloupec — jemné šedé kolečko s ikonou, pak nadpis, pak popis a pak řádek akcí.

Každá část je volitelná a vynechá se nezávisle. Žádná ikona, žádné kolečko. Ani nadpis, ani popis, a zmizí celý textový blok. Žádné akce, žádný řádek tlačítek. EmptyState::make() bez čehokoli nastaveného vykreslí prázdný vycentrovaný div, a proto je užitečné minimum nadpis plus jedna akce.

Popis dostane horní odsazení jen tehdy, když je nad ním nadpis, takže popis sám o sobě sedí tam, kde by byl nadpis, místo aby se vznášel pod mezerou.

Akce jsou předrenderované HTML, ne objekty akcí. Tohle lidi překvapí a stojí za to být přesný: setter je typovaný Htmlable|string, ale render cesta každou položku přetypuje přes (string) $action. Objekt se tedy přijme jen tehdy, když má __toString() — a Action z tohohle frameworku implementuje Htmlable bez toho, aby byl Stringable, takže předání akce napřímo vyhodí:

Error: Object of class NyonCode\WireCore\Actions\Action could not be converted to string

Předejte ji vykreslenou — ->toHtml(), nebo vlastní Blade řetězec:

->actions([$action->toHtml()])

Stav „žádné záznamy“ u tabulky i samostatný tag <x-wire::empty-state> se vykreslují přes tentýž partial, takže cokoli se tady naučíte, platí ve všech třech.

Základní použití

EmptyState::make()
    ->icon('outline:inbox')
    ->heading('Zatím žádné objednávky')
    ->description('Objednávky se tu objeví, jakmile první zákazník dokončí nákup.')

S tím, co se s tím dá dělat

use NyonCode\WireCore\Actions\Action;
 
EmptyState::make()
    ->icon('outline:users')
    ->heading('Žádní členové týmu')
    ->description('Pozvi někoho ke spolupráci na tomhle projektu.')
    ->actions([
        Action::make('invite')->label('Pozvat kolegu')->toHtml(),   
    ])

Všimněte si toho ->toHtml(). Když předáte víc tlačítek, zalomí se na další řádky a řádek je vycentrovaný pod popisem.

Closure místo řetězce

heading() i description() berou closure, vyhodnocovanou při čtení, takže zpráva může záviset na tom, na co se uživatel dívá:

EmptyState::make()
    ->icon('outline:magnifying-glass')
    ->heading(fn (): string => "Ničemu neodpovídá \"{$this->search}\"")   
    ->description('Zkus kratší dotaz nebo zruš filtry.')

Rozšířený příklad

Panel dashboardu, který ukáže buď svůj obsah, nebo empty state, uvnitř skutečného Livewire hostu:

use Livewire\Component;
use NyonCode\WireCore\Actions\Action;
use NyonCode\WireCore\Foundation\Schema\EmptyState;
use NyonCode\WireCore\Foundation\Schema\Section;
use NyonCode\WireForms\Forms\Form;
use NyonCode\WireForms\Forms\WithForms;
 
class ProjectOverview extends Component
{
    use WithForms;
 
    public ?array $data = [];
 
    public function form(Form $form): Form
    {
        return $form
            ->statePath('data')
            ->schema([
                Section::make('members')
                    ->label('Tým')
                    ->schema([
                        EmptyState::make()                                  
                            ->icon('outline:users')
                            ->heading('Zatím žádní členové týmu')
                            ->description('Pozvi někoho ke spolupráci na tomhle projektu.')
                            ->actions([
                                Action::make('invite')
                                    ->label('Pozvat kolegu')
                                    ->action(fn () => $this->invite())
                                    ->toHtml(),
                            ])
                            ->visible(fn (): bool => $this->members->isEmpty()),
                    ]),                                                      
            ]);
    }
 
    public function invite(): void
    {
        // ...
    }
}

visible() je ze sdíleného layoutového povrchu, takže empty state z markupu úplně zmizí, jakmile je co ukazovat.

Samostatný tag

Týž partial jako Blade tag, pro povrch, který žádné schéma nemá:

<x-wire::empty-state icon="outline:inbox" heading="Zatím žádné záznamy" />

Vlastní empty state tabulky se konfiguruje na tabulce, ne staví tady — viz Tabulky.

EmptyState API

->icon(string|Icon|null $icon)                     // v jemném kolečku nad nadpisem
->heading(string|Closure|null $heading)            // hlavní řádek
->description(string|Closure|null $description)    // vedlejší řádek pod ním
->actions(array $actions)                          // předrenderované HTML řetězce — viz Jak to funguje
->getIcon(): ?string
->getHeading(): ?string
->getDescription(): ?string
->getActionsHtml(): array

Všechno ostatní — visible(), hidden(), columnSpan(), schema() — je společný layoutový povrch. Viz Společné API layoutů.

Související

• Schema — slovník, do kterého tohle patří, a společný povrch
• Callout — druhá prime komponenta
• Akce — co patří do řádku tlačítek
• Tabulky — vlastní stav „žádné záznamy“ u tabulky