docs(ux): document command palette registry migration

2026-07-14 13:26:12 +02:00
parent cb37893366
commit 09a2649c56
1 changed files with 70 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Vendoo 1.44.0 – UX Slice 16: Command Palette Registry Migration
+
+## Referenz
+
+- Branch: `release/1.44.0-ux-foundation-production-update-v1`
+- Ausgangs-Head: `eabbafbebd9288a258971c0a0a8abbeb27c9ea20`
+- App-Ziel: Vendoo `1.44.0`
+- Updater: `3.4.0`
+
+## Problem
+
+Die globale Ctrl+K-Palette führte vor diesem Slice mit `VIEW_LABELS` und `collectCommands()` eine zweite statische Command-Quelle. Dadurch konnten Registry-Metadaten, Modulregistrierungen, Aliase, Berechtigungen, deaktivierte Zustände, Favoriten und zuletzt geöffnete Bereiche nicht vollständig und konsistent ausgewertet werden.
+
+## Umsetzung
+
+- `window.VendooCommands` bleibt alleinige Datenquelle der Palette.
+- Der bestehende Command-Vertrag wurde ausschließlich additiv um `aliases`, `visible`, `enabled` und `disabledReason` ergänzt.
+- `list(...)` löst Sichtbarkeit, Permission und Enablement vor der Darstellung auf.
+- Suchranking gewichtet Titel, Aliase, Keywords, Beschreibung und Gruppe; Favoriten und Recents liefern kontrollierte Ranking-Boosts.
+- `execute(...)` prüft den Command-Zustand unmittelbar vor der Ausführung erneut und emittiert bei Ablehnung `vendoo:command-blocked`.
+- Die Palette ruft ausschließlich `VendooCommands.execute(...)` auf. Sie führt keine direkte View-Navigation und keine fachliche Aktion aus.
+- Browser-History, Deep Links und Back/Forward bleiben unverändert im bestehenden globalen Navigationslayer.
+
+## Accessibility und UX
+
+- vollständige Tastaturnavigation mit Pfeiltasten, Home, End, Enter und Escape
+- Combobox-/Listbox-Vertrag mit `aria-activedescendant`
+- verständliche Anzeige deaktivierter Commands einschließlich Begründung
+- Fokusfalle im Dialog und verlässliche Rückgabe an den Auslöser
+- Live-Status für Trefferzahl, Auswahl und blockierte Commands
+- responsive Darstellung bis 320 px, Reduced Motion und 200-%-Zoom-taugliche Struktur
+- Ctrl+K überschreibt keine Eingabe- oder Contenteditable-Kontexte, solange die Palette geschlossen ist
+
+## Daten-, Security- und Betriebsgrenzen
+
+- keine Datenbankänderung
+- keine Migration
+- keine Route, API oder Modul-ID umbenannt
+- keine Netzwerkaufrufe aus Command Platform oder Palette
+- keine automatische Speicherung, Veröffentlichung, Installation, Deaktivierung oder Löschung
+- explizite Permission ohne auflösbaren Permission-Resolver wird in der UI nach dem Deny-by-default-Prinzip nicht dargestellt
+- serverseitige Berechtigungsprüfung bleibt maßgeblich
+
+## Verifikation
+
+Neues Gate: `npm run verify:command-palette-registry`
+
+Das Gate prüft:
+
+- Registry als alleinige Quelle
+- Wegfall von `VIEW_LABELS` und `collectCommands()`
+- Zustandsauflösung, Aliase und Ranking
+- Favoriten- und Recents-Integration
+- sichere Registry-Ausführung
+- Tastatur-, Fokus- und ARIA-Verträge
+- Loader-Reihenfolge
+- Ausschluss von Netzwerk-, Schreib-, Polling- und direkten Produktivaktionen
+- Einbindung in `verify:all`
+
+## Rollback
+
+Rollback erfolgt durch Rücknahme der Änderungen an:
+
+- `public/command-platform.js`
+- `public/global-navigation-ux.js`
+- `public/global-navigation-ux.css`
+- `tools/verify-command-palette-registry-1.44.0.mjs`
+- `package.json`
+
+Persistente Fach- oder Benutzerdaten werden durch diesen Slice nicht verändert. Die bestehenden Local-Storage-Keys für Favoriten und Recents bleiben unverändert.