# Frontend JavaScript

Letzte Aktualisierung: 2026-02-21

## Ordnerstruktur

- `/web/js/core`
  - technische Basismodule (DOM/Factories)
- `/web/js/components`
  - wiederverwendbare UI-Features
- `/web/js/pages`
  - seitenspezifische Hilfen (z. B. Listeninitialisierung)

## Initialisierung

- `/web/js/app-boot.js`
  - wird im `<head>` geladen
  - setzt früh UI-States (no-js/js, Sidebar-/Contrast-LocalStorage)
- `/web/js/app-init.js`
  - Modul-Entrypoint für Standardseiten
  - importiert Komponenten zentral
- `/web/js/app-login-init.js`
  - reduzierter Entrypoint für Loginseiten

## Modulkonvention (components/pages)

Empfohlenes Muster:

1. `init...()` Funktion exportieren
2. Früher Guard auf fehlende Elemente
3. Keine stillen Fehler verschlucken
4. Nur DOM/UI-Verhalten, keine Fachlogik

Template für neue Komponenten:

- `/web/js/components/_template.js`

## Defensive DOM-Nutzung

Nicht jede Seite hat jedes Element.

- Vor Zugriff immer Element-Existenz prüfen.
- Optional zentrale Helper (`app-dom.js`) verwenden.
- Module sollen auf nicht-passenden Seiten sauber no-op sein.

## Grid.js-Integration

- Gemeinsame Initialisierung über Core/Page-Utilities.
- Vendor-spezifische CSS-Anpassungen in:
  - `/web/css/vendor-overrides/gridjs.css`
- Bei dynamischen Rows mit Lightbox/Tooltips: nach Render Refresh triggern.

### Grid URL State Sync

`createServerGrid(...)` synchronisiert bei `urlSync: true` den Grid-Zustand zentral in die URL.

- Search + Filter (bestehendes Verhalten)
- Sortierung über `order` + `dir`
- Pagination über `page` (1-basiert)

Optionale Konfiguration:

```js
createServerGrid({
  // ...
  urlSync: true,
  urlState: {
    pageParam: 'page',
    sortOrderParam: 'order',
    sortDirParam: 'dir',
    cleanFirstPage: true,
    syncPage: true,
    syncSort: true
  }
});
```

Hinweise:

- `page=1` wird bei `cleanFirstPage: true` nicht in der URL gehalten.
- Übernommene URL-Werte werden validiert:
  - `page >= 1`
  - `dir` nur `asc|desc`
  - `order` nur bekannte Sort-Key-Spalten
- Bei Search-/Filter-Änderung wird auf Seite 1 zurückgesetzt.

## Linting

Prüfen mit:

```bash
npx eslint web/js
```

Auto-fix (nur für sichere Rule-Fixes):

```bash
npx eslint web/js --fix
```

Hinweis: `--fix` behebt format-/syntaxnahe Themen (z. B. fehlende Klammern), aber nicht automatisch alle Logikprobleme.
