filament-table-defaults

Files (5)

• SKILL.md
• advanced-filters.md · rules/
• editable-columns.md · rules/
• performance.md · rules/
• visual-defaults.md · rules/

SKILL.md (first lines)

# Filament Table Defaults

## Consistency First

Esta skill padroniza defaults locais da `Table` sem invadir defaults globais do Panel Provider. A tabela deve ser previsível: 25 itens por página, sort default coerente, search apenas em colunas display pesquisáveis e filtros úteis ao modelo.

Preserve decisões explícitas existentes. `created_at desc` é default para tabelas novas, não motivo para substituir ordenações semânticas como `name`, `title` ou `id desc` quando a tela já depende delas.

Densidade extra mora em `rules/`:

- `rules/editable-columns.md` — `TextInputColumn`, `SelectColumn`, `ToggleColumn`, `CheckboxColumn`.
- `rules/advanced-filters.md` — `Filter` com schema custom, `QueryBuilder`, filtros condicionais.
- `rules/performance.md` — `deferLoading()`, `persistFiltersInSession()`, `persistSortInSession()`, eager loading.
- `rules/visual-defaults.md` — `striped()`, `reorderable()`, `groups()`, `recordUrl()`, `recordAction()`.
- Para badges, `withCount()`, `counts()` e cache de contagens, aplicar `filament-cache-performance`.

## Quick Reference

- Consultar Laravel Boost `search-docs` antes de editar com `packages: ['filament/filament']` e queries `table pagination`, `default sort`, `table filters`, `searchable columns`.
- Paginação local: `->defaultPaginationPageOption(25)`. Se customizar `->paginated([...])`, inclua `25`.
- Sort novo: `->defaultSort('created_at', 'desc')` quando existir `created_at` e não houver sort explícito.
- Search: marcar `TextColumn` display com `->searchable()` ou `->searchable(['real_column'])` para valor computado.
- Filtros base: `TrashedFilter` para SoftDeletes, `SelectFilter` para enum/relationship, `TernaryFilter` para boolean, `Filter` com `->schema()` + `->query()` para intervalo.
- Actions de linha: namespace `Filament\Actions\*` (v5). Bulk actions: `->toolbarActions([...])` ou `->groupedBulkActions([...])` (v5).
- Toda action de tabela que abre modal exige `modalHeading(__('English'))` (ver `filament-action-with-modal-heading`).
- Contagens em coluna usam `TextColumn::make('items_count')->counts('items')`; cache de badge segue `filament-cache-performance`.

## Workflow

- [ ] Consultar docs versionadas via Laravel Boost `search-docs` com `packages: ['filament/filament']`.

- [ ] Mapear defaults existentes na tabela:

```bash
vendor/bin/sail bin grep -rE "defaultSort|defaultPaginationPageOption|paginated\(|paginationPageOptions\(|filters\(|recordActions\(|toolbarActions\(" app/Filament
```

- [ ] Em tabela nova ou sem paginação explícita, definir 25:

```php
use Filament\Tables\Table;

public static function configure(Table $table): Table
{
    return $table
        ->defaultPaginationPageOption(25);
}
```

- [ ] Se a tabela usar `paginated([...])` ou `paginationPageOptions([...])`, garantir que `25` está presente:

```php
return $table
    ->paginated([10, 25, 50, 100])
    ->defaultPaginationPageOption(25);
```

- [ ] Definir sort default sem sobrescrever ordem semântica existente:

```php
return $table
    ->defaultSort('created_at', 'desc');
```

Preserve `->defaultSort('name')`, `->defaultSort('title')`, `->defaultSort('id', 'desc')` ou sort de coluna de negócio quando a tela exige leitura alfabética, hierarquia ou ordem de domínio.

- [ ] Marcar search em colunas display reais:

```php
use Filament\Tables\Columns\TextColumn;

TextColumn::make('name')
    ->label(__('Name'))
    ->searchable()
    ->sortable();

TextColumn::make('display_name')
    ->label(__('Display Name'))
    ->searchable(['first_name', 'last_name']);
```

- [ ] Adicionar filtros base só quando o model/tela justificar:

```php
use Filament\Forms\Components\DatePicker;
use Filament\Tables\Filters\Filter;
use Filament\Tables\Filters\SelectFilter;
use Filament\Tables\Filters\TernaryFilter;
use Filament\Tables\Filters\TrashedFilter;
use Illuminate\Database\Eloquent\Builder;

return $table
    ->filters([
        TrashedFilter::make(),
        SelectFilter::make('status')
            ->label(__('Status'))
            ->options(StatusEnum::class),
        TernaryFilter::make('is_active')
            ->label(__('Active')),
        Filter::make('created_at')
            ->schema([
                DatePicker::make('created_from')->label(__('Created from')),
                DatePicker::make('created_until')->label(__('Created until')),
            ])
            ->query(fn (Builder $query, array $data): Builder => $query
                ->when($data['created_from'] ?? null, fn (Builder $query, string $date): Builder => $query->whereDate('created_at', '>=', $date))
                ->when($data['created_until'] ?? null, fn (Builder $query, string $date): Builder => $query->whereDate('created_at', '<=', $date))),
    ]);
```

- [ ] Para SoftDeletes, confirmar trait no model antes de usar `TrashedFilter::make()`.

- [ ] Para filtros complexos, ver `rules/advanced-filters.md`.

- [ ] Para colunas editáveis inline, ver `rules/editable-columns.md`.

- [ ] Para `deferLoading`, `persistFiltersInSession`, eager loading, ver `rules/performance.md`.

- [ ] Para badges, relation tab counts, `withCount()` ou cache de contagem, ver `filament-cache-performance`.

From CoringaWc/ai-first-kit, MIT.

More from CoringaWc/ai-first-kit