docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

2026-03-06 12:25:18 +01:00
parent 9caa0a4f75
commit 72886f4784
49 changed files with 564 additions and 180 deletions
--- a/docs/reference-frontend-javascript.md
+++ b/docs/reference-frontend-javascript.md
@@ -0,0 +1,341 @@
+# Frontend JavaScript
+
+Letzte Aktualisierung: 2026-03-06
+
+## 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:
+
+- bestehende Komponenten als Referenz verwenden (`/web/js/components/*.js`)
+
+## Page Module Contract (Hard Cut)
+
+Für seitenbezogene Initialisierung gilt verbindlich:
+
+- Kein inline `<script type="module">` in `pages/**` oder `templates/**`.
+- Pro Seite genau ein externes Modul unter `web/js/pages/*` laden.
+- Serverseitige Daten für dieses Modul über
+  `<script type="application/json" id="page-config-...">...</script>` bereitstellen.
+- Page-Module lesen Config zentral über `readPageConfig(...)` aus `web/js/core/app-page-config.js`.
+- JS-`src` in `pages/**` und `templates/**` nur über `assetVersion('...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.
+
+### Row Interaction (Globaler Standard)
+
+Listen mit `rowDblClick.getUrl(...)` nutzen standardmäßig eine zugängliche Row-Interaktion:
+
+- sichtbare Action-Spalte rechts (`Open`/`Edit`)
+- Doppelklick bleibt als Fallback aktiv
+- `Enter` auf fokussierter Zeile navigiert zur selben URL
+- Action-Header/Tooltip zeigt den Enter-Hinweis
+
+Optionale Konfiguration über `createServerGrid(...)`:
+
+```js
+createServerGrid({
+  // ...
+  rowDblClick: {
+    getUrl: (rowData) => new URL(`admin/users/edit/${rowData?.cells?.[1]?.data}`, appBase).toString(),
+  },
+  rowInteraction: {
+    enabled: true,
+    showActionButton: true,
+    keepDblClick: true,
+    enableEnterOnRow: true,
+    actionColumnLabel: 'Actions',
+    resolveActionLabel: (url) => (url.includes('/edit/') ? 'Edit' : 'Open'),
+  }
+});
+```
+
+Defaults:
+
+- `rowInteraction.enabled`: `true`, wenn `rowDblClick.getUrl` vorhanden ist
+- `showActionButton`: `true`
+- `keepDblClick`: `true`
+- `enableEnterOnRow`: `true`
+- `actionColumnLabel`: `language.actions.column` oder `'Actions'`
+
+Hinweis:
+
+- Falls eine Seite `actions.enabled: true` explizit setzt, wird keine zusätzliche automatische Row-Action-Spalte injiziert.
+
+### Grid Error Recovery
+
+Bei Grid-Fehlern rendert die Factory automatisch einen Retry-CTA im Error-State.
+
+- Label kommt aus `language.errorRetry` (Fallback: `Retry`).
+- Klick auf Retry lädt den Grid-Server-Request erneut.
+
+### Filter UX 2.0 (Globaler Standard)
+
+Für Listen gilt standardmäßig:
+
+1. Quick Search sichtbar außerhalb des Drawers.
+2. Restliche Filter im rechten Drawer (`data-filter-drawer-*`).
+3. Drawer arbeitet `apply-first` (Draft bis `Apply`).
+4. Aktive Filter werden als Chips angezeigt (`data-active-filter-chips`).
+5. Filter-Reset erfolgt über Chips (`Clear all filters`), nicht im Drawer.
+
+JS-Verkabelung:
+
+- Standard-Entrypoint ist `initStandardListPage(...)` aus `web/js/core/app-grid-factory.js`.
+- Der Wrapper kapselt intern `createServerGrid(...)` + (bei `mode: 'drawer'`) `initListFilterExperience(...)`.
+- Bei Apply/Clear wird URL mit `pushState` fortgeschrieben.
+- Save-Filter-Usecases lesen den angewandten Zustand über `gridConfig.baseUrl()`.
+- Chip-State-Logik ist zentral im Wrapper verdrahtet (Default: `app-list-filter-state.js`).
+
+Search-only-Ausnahme:
+
+- Listen ohne zusätzliche Filter initialisieren über denselben Wrapper mit `mode: 'search-only'` (ohne Drawer/Chips).
+
+### Standard-List-API
+
+Für Listen-Templates gilt:
+
+- `initStandardListPage({ grid, filters, hooks })` verwenden.
+- `grid.filterSchema` serverseitig aus `filter-schema.php` (`gridSchemaClientFilters(...)`) übergeben.
+- Optional zusätzliche Spezialfilter über `grid.extraFilters`.
+- Bei Drawer-Listen `filters.mode: 'drawer'`, bei Search-only `filters.mode: 'search-only'`.
+
+Regel:
+
+- keine direkten Aufrufe von `gridFiltersFromSchema(...)` in Listen-Templates
+- keine direkten Aufrufe von `initListFilterExperience(...)` in Listen-Templates
+- keine inline `filters: [...]`-Arrays in Listen-Templates
+- MultiSelect-Filter immer als CSV-Key (`*_ids`, `actions`, `event_types` etc.)
+
+Serverseitig passendes Template-Markup:
+
+- normale Select-Filter über `selectFilter(...)`
+- MultiSelect-Filter über `multiSelectFilter(...)`
+
+### List Titlebar Standard
+
+Für Listen-Titlebars gilt:
+
+- Titlebar über `templates/partials/app-list-titlebar.phtml` rendern.
+- Titel über `$listTitle` setzen.
+- Aktionen über `$listTitleActionsHtml` als Slot (captured HTML) übergeben.
+
+Beispiel:
+
+```php
+<?php
+$listTitle = t('Users');
+ob_start();
+?>
+<a role="button" class="primary" href="admin/users/create"><?php e(t('Create user')); ?></a>
+<?php
+$listTitleActionsHtml = ob_get_clean();
+require templatePath('partials/app-list-titlebar.phtml');
+?>
+```
+
+### List Tabs Standard
+
+Für Tenant- oder Kontext-Tabs in Listen gilt:
+
+- Tabs über `templates/partials/app-list-tabs.phtml` rendern.
+- Tab-Items über `$listTabsItems` mit `href`, `label`, `active` übergeben.
+- Optional `id` über `$listTabsId` setzen.
+
+### List Purge Action Standard
+
+Für Purge-Buttons in Titlebar-Actions gilt:
+
+- Purge-Markup über `templates/partials/app-list-purge-action.phtml` rendern.
+- Formular/CSRF/Button/Confirm werden zentral übergeben via:
+  - `$listPurgeEnabled`
+  - `$listPurgeFormId`
+  - `$listPurgeAction`
+  - `$listPurgeConfirmMessage`
+  - `$listPurgeButtonLabel`
+
+### Aside Grouped Navigation + Persisted Details State
+
+Für gruppierte Sidebar-Navigation mit einklappbaren `details` gilt:
+
+- Zentraler Storage-Helper: `web/js/core/app-details-open-state.js` (`initPersistedDetailsGroup(...)`).
+- Standardgruppen über `details[data-details-key]`.
+- Persistenz-Aktivierung über:
+  - `data-details-storage="..."` (allgemein, z. B. Detailseiten)
+  - `data-aside-details-storage="..."` (Aside-Panels)
+- Optionales Aktiv-Verhalten im Aside über `data-aside-details-open-active="1"`:
+  - aktive Gruppe bleibt immer offen
+  - effektive Open-Keys = `persistedOpenKeys ∪ activeOpenKeys`
+
+Admin-Aside-Standard:
+
+- Storage-Key: `aside-admin-sections-v1`
+- Gruppenkeys:
+  - `admin-organization`
+  - `admin-roles-permissions`
+  - `admin-automation`
+  - `admin-monitoring`
+  - `admin-logs`
+  - `admin-system`
+
+### Detail Page Standard
+
+Für Create/Edit-Detailseiten gilt:
+
+- Hauptformular über `data-standard-detail-form="1"` explizit opt-in markieren.
+- Initialisierung läuft zentral über `initStandardDetailPage(...)` aus `web/js/core/app-detail-page-factory.js`.
+- Auto-Init erfolgt über `web/js/components/app-standard-detail-page.js` (in `app-init.js` eingebunden).
+
+Standardverhalten:
+
+- Dirty-State über serialisierte `FormData`-Diffs (initial vs. aktuell).
+- `beforeunload`-Warnung nur bei ungespeicherten Änderungen.
+- Back/Cancel-Link in `.app-details-titlebar h1 a` fragt bei Dirty-State per Confirm.
+- `Cmd/Ctrl+S` triggert primären Save/Create-Button (`data-detail-save-primary="1"`).
+- Submit-Lock/Confirm laufen zentral über die Detail-Action-Policy.
+- Bei Dirty-State wird in der Titlebar automatisch ein kleiner Hinweis mit Feldanzahl gezeigt.
+
+### Detail Action Policy
+
+Für standardisierte Detailseiten gilt zusätzlich:
+
+- `initStandardDetailPage(...)` bindet intern `initDetailActionPolicy(...)` aus `web/js/core/app-details-action-policy.js`.
+- Aktivierung pro Seite über `data-detail-action-policy="1"` auf `.app-details-titlebar` (Default im Shared-Partial aktiv).
+- Confirm nicht mehr inline per `onclick/onsubmit`, sondern über `data-detail-confirm-message`.
+- Aktionssemantik über `data-detail-action-kind` (z. B. `save`, `save-close`, `delete`, `danger`).
+- Optionaler Lock-Override über `data-detail-submit-lock="none"` (Default: `form`).
+
+### Global Confirm Actions
+
+Für allgemeine Form-/Button-Confirms außerhalb der Detail-Policy gilt:
+
+- zentral über `web/js/components/app-confirm-actions.js`
+- Dialog-Engine zentral über `web/js/core/app-confirm-dialog.js` (`confirmDialog.confirm(...)`)
+- Confirm-Text über `data-confirm-message` bzw. auf Detail-Aktionen `data-detail-confirm-message`
+- optionale Dialog-Meta über
+  - `data-confirm-title`, `data-confirm-confirm-label`, `data-confirm-cancel-label`, `data-confirm-variant`, `data-confirm-focus`
+  - analog für Detail-Aktionen: `data-detail-confirm-*`
+- kein direktes `window.confirm(...)` in App-JS
+- keine inline `onclick="return confirm(...)"` / `onsubmit="return confirm(...)"` verwenden
+
+### Frontend Telemetry Standard
+
+Für UX-/Fehler-Telemetrie im Frontend gilt:
+
+- zentral über `web/js/core/app-telemetry.js` (`telemetry.capture(...)`)
+- `warnOnce(...)` sendet standardisiert `frontend.warn_once`
+- AJAX-/Fetch-Fehler laufen zentral über den globalen Fetch-Hook als `frontend.ajax_error`
+- keine neuen Console-only-Warnpfade für relevante UX-Probleme ohne Telemetrie
+- Payloads nur mit Whitelist-Feldern und ohne sensitive Rohdaten (keine Tokens/Query-Parameter/Stacktraces)
+
+### Detail Validation Summary Standard
+
+Für serverseitige Formularfehler in Create/Edit-Templates gilt:
+
+- Fehlerausgabe über `templates/partials/app-details-validation-summary.phtml`.
+- Keine inline `<div class="notice" data-variant="error">`-Blöcke mit `foreach ($errors as $error)` mehr.
+- Standardtitel kommt aus `t('Please review the following errors')`.
+- In Action-Handlern strukturierte Feld-Errors als `$validationSummaryErrors = $errorBag->toArray();` bereitstellen.
+
+Template-Beispiel:
+
+```php
+<?php
+$validationSummaryErrors = $validationSummaryErrors ?? ($errors ?? []);
+require templatePath('partials/app-details-validation-summary.phtml');
+?>
+```
+
+Optional strukturierte Einträge:
+
+- `['message' => '...', 'fieldName' => 'email']`
+- `['message' => '...', 'fieldId' => 'email']`
+- `['email' => ['Required']]` (FormErrors-ähnliche Map)
+
+JS-Verhalten über `initStandardDetailPage(...)`:
+
+- Klick auf Validation-Link fokussiert das passende Feld.
+- Bei vorhandener Summary wird initial das erste betroffene Feld (oder Summary) fokussiert.
+- Betroffene Felder werden zentral mit `aria-invalid="true"` und `aria-describedby` (Summary-ID) markiert.
+
+## Laufzeit-Check (ohne Node)
+
+Prüfen im Browser:
+
+1. DevTools öffnen (Console, optional Preserve log aktivieren).
+2. Kernseiten laden (`/admin/users`, `/address-book`, Audit-Listen).
+3. Filter setzen/zurücksetzen, Row-Action-Button + Enter + Doppelklick sowie Bulk-Aktionen testen.
+4. Erwartung: keine JavaScript-Errors und keine Unhandled Promise Rejections.