Vrstva gest

Tabulka wire-table se umí chovat jako desktopová aplikace: šipky procházejí řádky, Shift roztahuje rozsah, myš označuje tažením přes checkboxový sloupec, pravý klik otevře menu řádku, ? vysvětlí zkratky a fill handle roztáhne jednu hodnotu přes mnoho buněk.

Pro back office je to přesně ono. Pro veřejný výpis je to obvykle špatně — zvýrazněný řádek a zabavený pravý klik tam v lepším případě jen ruší.

Je to proto jeden vypínač a tabulka začíná na té tiché straně:

->gestures()

Tohle je ta desktopová tabulka. Bez toho dostanete obyčejnou webovou — tu, kterou většina stránek chce.

Co tabulka dostane, když si neřekne

Každý způsob ovládání řádku je vypnutý, dokud si o něj neřeknete. Tři schopnosti mění chování tabulky vůči návštěvníkovi, který ji ovládat nezamýšlel, a všechny tři čekají:

• Klávesová navigace dá řádky do pořadí tabulátoru, označí aktivní řádek a začne odpovídat na šipky a mod+klávesu.
• Označování tažením promění stisk v checkboxovém sloupci na blokový výběr — gesto, které lidé najdou omylem dřív než schválně.
• Rozsahový výběr přepisuje význam modifikovaného kliku: Shift+klik přestane být klikem a stane se z něj „všechno mezi tímhle a posledním“. Ve správci souborů správně, v seznamu článků překvapivě.

Tabulka se selectable() proto začíná jako zaškrtávátka a nic víc a delegovaný Alpine controller se ani nevykreslí. Co zůstává povolené, stejně potřebuje vlastní pozvánku: kontextové menu potřebuje navázané akce, fill handle potřebuje ->fillHandle() a nápověda ? potřebuje klávesovou vrstvu, kterou tenhle default nechává vypnutou.

// Obyčejný výpis. Checkboxy fungují a nic jiného:
// žádné šipky, žádné označování tažením, žádný modifikovaný klik s jiným významem.
Table::make()->selectable()
 
// Ta samá tabulka jako aplikace.
Table::make()->gestures()->selectable()

Když chcete jít opačným směrem — žádné kontextové menu, žádné rozsahy, žádný fill handle, vůbec nic — řekněte si o to:

->gestures(false)

Co se počítá jako gesto

Šest schopností, každá zvlášť přepínatelná. „Výchozí“ je to, co dostane tabulka, která gestures() nikdy nezavolá:

mod je Ctrl na Windows a ⌘ na macOS.

¹ Povolená, ale čte klávesovou vrstvu — s výchozím nastavením se tedy neotevře. ² Povolený, ale tabulka si o něj pořád musí říct přes ->fillHandle().

S výchozím nastavením tedy tabulka nabízí jen gesta, která sama deklarovala: kontextové menu, pokud je na něj navázaná akce, a fill handle, pokud si o něj řekla.

Kombinování

Předejte closure. Dostane gesta téhle tabulky a nastaví je na místě — návratová hodnota se ignoruje, takže funguje jak fluent řetězec, tak víceřádkové tělo.

->gestures(fn (TableGestures $g) => $g
    ->keyboard()          // šipky, Enter, zkratky …
    ->dragSelect(false))  // … ale pořád žádné označování tažením

Každý setter bere bool, takže ->contextMenu(false) se čte stejně dobře jako ->contextMenu().

Můžete taky předat hotovou sadu, což se hodí, když má víc tabulek sdílet jeden domácí styl:

use NyonCode\WireTable\Support\TableGestures;
 
$readOnly = TableGestures::none()->contextMenu();
 
// …a pak v každé tabulce:
->gestures($readOnly)

TableGestures::defaults(), TableGestures::all() a TableGestures::none() jsou tři výchozí body: dodávaný default, všechno, nic.

Povolení není zapnutí

Každá schopnost je povolení, nikdy spouštěč. Zapnout ji neznamená vyrobit to, co řídí:

• dragSelect a rangeSelection pořád potřebují ->selectable() (nebo ->bulkActions(), které ho implikují) — rozsah musí mít v čem růst.
• fillHandle pořád potřebuje ->fillHandle() na tabulce a editovatelné sloupce.
• shortcutHelp pořád potřebuje klávesovou vrstvu, protože právě ta na klávesu poslouchá.

Takže ->gestures(fn ($g) => $g->dragSelect()) na tabulce bez selectable() nezmění nic. Je to záměr: vrstva gest rozhoduje, co tabulka smí, a zbytek API tabulky rozhoduje, co má.

keyboard() má tři stavy

Ostatních pět schopností jsou prosté booleany. keyboard je třístavová, protože „zapnuto“ tu musí znamenat dvě různé věci:

gestures() nechává klávesnici na null místo aby ji zapínalo natvrdo: tabulka bez record actions a bez výběru nemá pro šipky co dělat a putovní tabindex nad netečnými řádky je horší než žádný:

Table::make()->gestures()                                          // není grid
Table::make()->gestures()->selectable()                            // je grid
Table::make()->gestures(fn (TableGestures $g) => $g->keyboard(true))   // grid tak jako tak

Co vrstva neřídí

Výslovně deklarovaná record action funguje dál. Vazba jako

->recordAction(RecordAction::make(Action::make('view'))->onClick())

je vědomé rozhodnutí o téhle tabulce, ne implicitní afordance, kterou si tabulka zapnula sama — takže gestures(false) přežije. Vrstva gest řídí jen to, co by si tabulka jinak zapnula sama od sebe.

Jedinou výjimkou je ->onKey(), které potřebuje klávesovou vrstvu, aby měla čím poslouchat. S vypnutou keyboard nemá vazba onKey() odkud vystřelit.

Samotný výběr zůstává taky nedotčený. I s vypnutými gesty fungují checkboxy, oba ovladače „vybrat vše“ i bulk bar přesně jako dřív — přijdete o zkratky k nim, ne o funkci. Buňka výběru pak na modifikovaný klik reaguje přepnutím, protože s vypnutými rozsahy by na něj nereagoval nikdo jiný.

Označení aktivního řádku

Řádky nesou marker aktivního řádku tehdy, když nějaké gesto potřebuje odkud růst — tedy když tabulka používá grid semantiku, rozsahový výběr nebo označování tažením.

Tabulka, které zbyla jen deklarovaná klik akce, neoznačuje nic. Klik tam otevře záznam a jde se dál; zvýrazněný řádek, který po něm zůstane, by byl aplikační afordance na stránce, která o žádnou nežádala.

Výchozí nastavení pro celý projekt

Nastavte jednou pro všechny tabulky:

// config/wire-table.php
'defaults' => [
    'gestures' => true,
],

null (nebo chybějící klíč) ponechá dodávaný default popsaný výše, true povolí všechno všem tabulkám — back office si vrstvu zapne jednou tady místo u každé tabulky — false nepovolí nic a mapa kombinuje:

'gestures' => ['keyboard' => true, 'drag_select' => false],

Klíče schopností se párují volně — drag_select, drag-select, dragSelect i dragselect jsou tentýž klíč. Neznámý klíč vyhodí TableConfigurationException, místo aby tiše nedělal nic: překlep v povolení je přesně ten druh chyby, která se projeví až za půl roku jako „proč tohle nefunguje“.

Per-table ->gestures(...) vždy přebije výchozí hodnotu z configu.

Vypnuto je i na serveru

Vypnutí schopnosti není věc toho, že klient ignoruje eventy. Jde s tím i markup a endpointy:

• Delegované Alpine controllery se nevykreslí. Tabulka, které zbylo jen vypnutí gest, nemontuje controller vůbec a jejich bundly nepřikládá. (S @wireStackScripts v layoutu jsou bundly v dokumentu tak jako tak — ale nic je nemontuje, takže stojí jeden cachovaný request a žádné chování.)
• Tabulka přestane být ARIA grid: žádné role="grid", role="row", žádný putovní tabindex.
• Řádky nejsou fokusovatelné, takže klik nikomu nesebere fokus.
• Fill endpoint odmítá. Vypnutý fillHandle zavře fillTableCells na serveru, ne jen úchyt v UI.
• Legenda zkratek zahodí řádky, které už neplatí — s vypnutými rozsahy se Shift+šipka v nápovědě ? neobjeví, protože nefunguje.

To poslední je obecné pravidlo: legenda se generuje z toho, co tabulka opravdu dělá, takže se nemůže rozejít se skutečností.

Na telefonu jsou z gest tlačítka

Tabulka řízená gesty je desktopová myšlenka. Na telefonu není dvojklik, není pravý klik a není hover, kterým by se jeden nebo druhý dal objevit — takže record action, která je na desktopu jen chováním, by na skládané mobilní kartě byla nedosažitelná.

Vykreslí se tam proto jako obyčejné tlačítko, a jen tam:

->recordAction(RecordAction::make(Action::make('open'))->onDoubleClick())

Fallback si dává pozor, aby nic nezdvojil:

• Akce už přítomné v ->actions() si drží pořadí a record actions se přidají za ně.
• recordAction('edit'), které jen odkazuje na akci deklarovanou v ->actions(), ukáže jedno tlačítko — ne totéž dvakrát.
• Akce povýšená do sloupce přes ->alsoInRowActions() už tlačítkem je, takže se nechá být.
• Fallbacková tlačítka se počítají do ->collapseActionsOnMobile(), takže karta tiše nepřeroste práh, který jste nastavili.

Když má karta zůstat čistá, vypněte to:

->recordActionButtonsOnMobile(false)

Na tabletu zůstanou gesta, prstem

Tablet je dost široký na desktopovou tabulku, takže nedostane skládanou kartu ani její tlačítka — řádek si drží svá gesta. Prst zachová, co které znamená:

Menu, které prst otevře, je kontextové menu řádku plus každá record action, která je jen chováním a v menu ještě není — vazby na dvojklik a klávesy, na které prst jinak nedosáhne. A protože dlouhé podržení nikdo neuhodne, tabulka se sloupcem akcí v něm na dotykové obrazovce ukáže i ⋯, které otevře totéž menu:

->actions([EditAction::make()])
->recordAction(RecordAction::make(Action::make('open'))->onDoubleClick())   
->recordAction(RecordAction::make(Action::make('archive'))->onKey('Delete'))  

⋯ se ukáže všude, kde řádek vůbec nějaké menu má — tabulka, jejíž gesta už v kontextovém menu jsou, nepřidá žádnou položku a tlačítko přesto potřebuje, protože pravé tlačítko má jen myš.

Nic se nedeklaruje: je to fallback z telefonu, jen dosažený jinak, takže platí stejná pravidla — akce už v ->actions() nebo povýšená přes ->alsoInRowActions() se neuvede dvakrát, ->recordActionButtonsOnMobile(false) to vypne, a stejně tak contextMenu(false), protože dlouhé podržení zastupuje pravé tlačítko. ⋯ se ukáže jen tam, kde platí (pointer: coarse); myš ho ani přidané položky nikdy neuvidí.

Přehled API

Všechno, co vrstva nabízí, na jednom místě.

Na tabulce

Čtecí metody, hodí se ve vlastní view nebo v testu:

Na TableGestures

use NyonCode\WireTable\Support\TableGestures;

Povolení a výsledek jsou dvě různé otázky: allowsDragSelect() říká, že tabulka označovat tažením smí, usesDragSelect() říká, že to opravdu dělá (k tomu potřebuje ještě selectable()).

Recepty

Veřejný výpis. Nedělejte nic:

$table->model(Post::class)->columns([...]);

Back-office grid. Jedno volání, nebo 'gestures' => true v configu pro celý projekt:

$table->gestures()->selectable()->bulkActions([DeleteBulkAction::make()]);

Klik na řádek ho otevře, jinak tichá tabulka. Deklarovaná record action stojí mimo vrstvu, takže tady gestures() netřeba:

$table->recordAction(RecordAction::make(Action::make('view'))->onClick());

Klávesnici ano, tažení ne. Pro dlouhé seznamy, kde by nechtěné tažení vybralo sto řádků:

$table->gestures(fn (TableGestures $g) => $g->keyboard())->selectable();

Domácí styl napříč tabulkami. Sadu postavte jednou a předávejte ji:

// app/Tables/Gestures.php
public static function backOffice(): TableGestures
{
    return TableGestures::all()->dragSelect(false);
}
 
// v každé tabulce
$table->gestures(Gestures::backOffice());

Tabulka ve stránce s vlastní obsluhou klávesnice. Nechte si myší půlku:

$table->gestures(fn (TableGestures $g) => $g->rangeSelection()->dragSelect())->selectable();

Rozsahy ano, tažení ne. Shift+klik pro blok, bez tažení, které vybere omylem:

$table->gestures(fn (TableGestures $g) => $g->rangeSelection())->selectable();

Když něco nefunguje

Jak vybrat

Viz také

• Výběr řádků — co dělá které výběrové gesto
• Record actions — navázání akce na gesto řádku
• Pokročilé — fill handle