> Źródło: https://redai.pl/dev/widoki-i-wyglad/ (dokumentacja modułów portalu redAi). Cała dokumentacja w jednym pliku: https://redai.pl/dev/moduly.md

## Widoki i wygląd

Widoki z `widoki/` wołacie jako `view('<klucz>::nazwa')`. Moduł ma wyglądać jak reszta portalu, więc używacie wspólnych elementów, a nie własnego CSS.

Zasady obowiązkowe:

1. Każdy ekran modułu dziedziczy `layouts.app`, ustawia `@section('header', 'Narzędzia')` i zaczyna się od `@include('tools._naglowek', [...])`. Nagłówek daje pasek „Narzędzia › Nazwa”, powrót, zakładki i okno ustawień modułu z sekcją Widoczność i Pomocą.
2. Tylko klasy `ui-*`: `ui-page`, `ui-stack`, `ui-card`, `ui-card--flat`, `ui-field`, `ui-label`, `ui-input`, `ui-textarea`, `ui-btn`, `ui-btn--primary`, `ui-rows`, `ui-row`, `ui-empty`, `ui-badge` i inne. Pełny wzornik z przykładami jest na każdej instancji pod `/administracja/dev`.
3. **Bez własnych hero**, wielkich banerów i kolorowych teł. Ekran modułu to narzędzie pracy, nie strona reklamowa.
4. **Tryb ciemny działa sam**, jeśli kolory bierzecie z tokenów `--ui-*` (np. `var(--ui-ink)`, `var(--ui-line)`, `var(--ui-card)`). Nie wpisujcie kolorów na sztywno (`#fff`, `black`). Portal przełącza motyw atrybutem `data-theme` na `<html>` i podmienia tokeny.
5. Przycisk „+ Nowy X” idzie do sekcji `narz-akcje` jako `ui-btn--primary`, nigdy jako zakładka. Ustawienia rekordu otwieracie w oknie z auto-zapisem, bez przycisków Zapisz i Anuluj.
6. Szukajka listy: `ui-search narz-szukaj`, stronicowanie: `narz-strony`.
7. Alpine.js jest w portalu, możecie używać `x-data` bez dokładania bibliotek.

```blade
@extends('layouts.app', ['title' => 'Faktury kosztowe'])
@section('header', 'Narzędzia')

@section('narz-akcje')   {{-- przyciski po prawej w wierszu linków --}}
    <a href="{{ route('faktury_kosztowe.create') }}" class="ui-btn ui-btn--primary ui-btn--sm">Nowa faktura</a>
@endsection

@section('content')
<div class="ui-page ui-page--szeroka ui-stack">
    @include('tools._naglowek', ['nazwa' => 'Faktury kosztowe', 'klucz' => 'faktury_kosztowe'])
    <div class="ui-card ui-card--flat">...</div>
</div>
@endsection
```

Parametry `tools._naglowek`:

| Parametr | Co robi |
|---|---|
| `nazwa` | Nazwa modułu w pasku. |
| `klucz` | Klucz modułu (włącza okno ustawień, Widoczność i przypięcie do menu). |
| `pod` | Podtytuł pod nazwą. |
| `badge` | Odznaka obok nazwy. |
| `pigulki` | Zakładki ekranu: lista linków. |
| `wroc`, `wrocLabel` | Adres i napis linku powrotu. |
| `rekord` | Nazwa otwartego rekordu (np. tytuł faktury) w pasku. |
| `ustawieniaStart`, `ustawieniaOtworz` | Która sekcja okna ustawień otwiera się pierwsza i czy okno ma się otworzyć od razu. |

Sekcje, które możecie wypełnić w widoku: `narz-akcje` (przyciski po prawej), `narz-ust-nav` i `narz-ust-sekcje` (własne sekcje okna ustawień modułu), `narz-pomoc` (treść Pomocy w oknie).

Wspólne elementy portalu (opis parametrów jest w komentarzu na górze każdego pliku):

| Element | Do czego |
|---|---|
| `tools._naglowek` | Pasek modułu, zakładki, okno ustawień z Widocznością i Pomocą. |
| klasy `ui-*` | Karty, przyciski, pola, tabele, zakładki, okna. Wzornik: `/administracja/dev`. |
| `partials._edytor-tresci` | Edytor WYSIWYG. Obrazy idą na `route('narzedzia.obraz')` i wracają jako `/strony-pliki/<losowa nazwa>`. |
| `App\Support\CzystyHtml` | Czyszczenie HTML z edytora białą listą, zanim trafi do bazy. |
| `partials._tresc-style` | Style treści z edytora przy wyświetlaniu. |
| `partials._adres-publiczny` | Wiersz „Adres” z krótkim adresem `/<adres>` i kopiowaniem linku. |
| `App\Support\AdresyPubliczne` | `losowy()`, `zajety($adres, $rekord)` dla krótkich adresów (razem z hakiem `modeleAdresow`). |
| `partials._widocznosc` + trait `App\Models\Concerns\WidocznoscJakCzat` | Kto widzi rekord: wszyscy, zalogowani albo wybrane osoby i grupy. |
| `partials._wyglad-i-menu` | Wygląd rekordu (cały ekran albo w portalu) i przypięcie do menu. |
| `partials._pliki` | Panel plików jak w czacie i projekcie. |
| `partials._ikona-ust` | Ikona zębatki ustawień. |
| trait `Spatie\Activitylog\Traits\LogsActivity` | Dziennik zmian rekordu. |

Nie kopiujcie tych plików do modułu. Gdy portal je poprawi, moduł dostanie poprawkę sam.