Megamenu/README.md

# SharePoint MegaMenu

Barrierearme, dreistufige Portalnavigation auf Basis von SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019.

| Eigenschaft | Wert |
|---|---|
| Version | 1.1.0 |
| SharePoint Framework | SPFx 1.4.1 |
| Node.js | 8.17.0 |
| Zieloberfläche | Moderne SharePoint-Seiten |
| Paket | `sharepoint/solution/mega-menu.sppkg` |

## Funktionen

- Dreistufige Navigation aus einem Managed-Metadata-Termset
- Auswahl des Termsets per GUID oder, abwärtskompatibel, per Name
- Benutzerdefinierte Sortierung aus dem Term Store
- Unterstützung der Navigations-Eigenschaften `_Sys_Nav_SimpleLinkUrl`, `_Sys_Nav_TargetUrl` und `_Sys_Nav_HoverText`
- Auflösung von `~sitecollection` in Navigations-URLs
- Markierung des aktuellen Menüpunktes und seiner übergeordneten Einträge
- Bedienung mit Maus, Tastatur und Touch
- Responsive Darstellung
- Optionales zusätzliches Stylesheet
- Taxonomy-Cache mit konfigurierbarer Ablaufzeit
- Bereinigter SPFx-Lifecycle ohne verbleibende globale Event Listener
- Deutsche und englische Statusmeldungen

## Architektur

```text
UserCustomAction.ClientSideComponentProperties
                  │
                  ▼
MegaMenuApplicationCustomizer
                  │
                  ├── TaxonomyNavigationService
                  │       └── SPTermStorePickerService
                  │               └── Default Site Collection Term Store
                  │
                  └── MegaMenuRenderer
                          ├── semantische Navigation
                          ├── Fokus- und Tastatursteuerung
                          └── responsive Darstellung
```

Das MegaMenu liest seine Laufzeitkonfiguration aus der site-scoped UserCustomAction. Es enthält keine eigene Administrationsoberfläche. Die zentrale Pflege soll über die separate Solution **PortalSettings** erfolgen.

## Voraussetzungen

- SharePoint Server Subscription Edition oder SharePoint Server 2019
- konfigurierter App Catalog
- konfigurierter App Management Service
- ein Termset im Standard-Term-Store der Site Collection
- Leseberechtigung der Benutzer auf den Managed-Metadata-Service
- für Entwicklung und Build: Node.js 8.17.0 und eine zu SPFx 1.4.1 passende npm-Version

## Konfiguration

Die UserCustomAction unterstützt folgende `ClientSideComponentProperties`:

```json
{
  "termSetId": "6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc",
  "termSetName": "Global Navigation",
  "cacheMinutes": 15,
  "cssUrl": "/SiteAssets/megamenu/megamenu-custom.css",
  "debug": false
}
```

| Eigenschaft | Typ | Standard | Beschreibung |
|---|---:|---:|---|
| `termSetId` | GUID | leer | Bevorzugte, eindeutige Identifikation des Termsets |
| `termSetName` | String | leer | Rückwärtskompatibler Fallback, wenn keine gültige `termSetId` vorhanden ist |
| `cacheMinutes` | Zahl | `15` | Gültigkeit des Session-Caches, zulässig sind 1 bis 1440 Minuten |
| `cssUrl` | String | leer | Relatives/same-origin Stylesheet oder externe HTTPS-Adresse |
| `debug` | Boolean | `false` | Aktiviert zusätzliche Konsolenausgaben |

`termSetId` hat Vorrang vor `termSetName`. Für neue Installationen wird die GUID empfohlen, weil Termset-Namen nicht zwingend eindeutig sind.

### Kompatibilität mit PortalSettings

Die bisherige PortalSettings-Version verwaltet `termSetName`, `cssUrl` und `debug`. Das MegaMenu 1.1.0 bleibt damit vollständig lauffähig und verwendet für nicht vorhandene `cacheMinutes` automatisch 15 Minuten.

Damit auch `termSetId` und `cacheMinutes` zentral bearbeitet werden können, muss das MegaMenu-Formular in PortalSettings um diese beiden Eigenschaften ergänzt werden. Bis dahin können sie über das Deployment-Skript gesetzt werden. Speichert eine ältere PortalSettings-Version anschließend erneut, werden die beiden noch unbekannten Eigenschaften entfernt; das MegaMenu fällt dann kontrolliert auf `termSetName` und den Standard-Cache zurück.

## Termset-Aufbau

Die Darstellung unterstützt drei Ebenen:

```text
Ebene 1: Hauptnavigation
├── Ebene 2: Kategorie
│   ├── Ebene 3: Link
│   └── Ebene 3: Link
└── Ebene 2: Kategorie
```

Für Zieladressen werden die lokalen benutzerdefinierten Eigenschaften des Terms ausgewertet:

1. `_Sys_Nav_SimpleLinkUrl`
2. `_Sys_Nav_TargetUrl`

Optional kann `_Sys_Nav_HoverText` als ergänzender Hilfetext verwendet werden. Veraltete Terms werden nicht angezeigt. Terms, die nicht für Tagging verfügbar sind, bleiben für Navigationsszenarien sichtbar.

## Build

SPFx 1.4.1 verwendet die Legacy-Gulp-Toolchain. Neuere Node-Versionen sind nicht kompatibel.

```powershell
npm install
npm run package
```

Alternativ einzeln:

```powershell
gulp clean
gulp bundle --ship
gulp package-solution --ship
```

Das fertige Paket befindet sich anschließend unter:

```text
sharepoint/solution/mega-menu.sppkg
```

## Deployment

1. `mega-menu.sppkg` in den App Catalog laden.
2. Die Solution freigeben.
3. Die App in der gewünschten Site Collection installieren.
4. Das MegaMenu site-scoped registrieren.

Empfohlen mit Termset-GUID:

```powershell
.\deployment\add-megamenu.ps1 `
  -SiteUrl 'https://sharepoint/sites/portal' `
  -TermSetId '6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc' `
  -TermSetName 'Global Navigation' `
  -CacheMinutes 15 `
  -CssUrl '/SiteAssets/megamenu/megamenu-custom.css'
```

Abwärtskompatibel nur mit Namen:

```powershell
.\deployment\add-megamenu.ps1 `
  -SiteUrl 'https://sharepoint/sites/portal' `
  -TermSetName 'Global Navigation'
```

Das Skript entfernt ältere web-scoped Registrierungen derselben Komponente und erstellt beziehungsweise aktualisiert eine site-scoped UserCustomAction mit dem Description-Tag `MSFT-Custom-Solution:MegaMenu`. Dieses Tag wird von PortalSettings zur Erkennung verwendet.

## Zusätzliches CSS

Zulässig sind:

- serverrelative oder relative Pfade derselben SharePoint-Origin,
- absolute URLs derselben Origin,
- externe URLs ausschließlich über HTTPS.

Nicht-HTTP(S)-Schemes und unverschlüsselte externe HTTP-Adressen werden zur Laufzeit verworfen.

Die wichtigsten CSS-Klassen sind:

```css
#CustomNavigation { }
#Mega-Menu { }
.mega-menu-top-level { }
.mega-menu-top-item { }
.mega-menu { }
.mega-menu-grid { }
.mega-menu-category { }
.mega-menu-links { }
```

Viele Farben und Abstände können über CSS Custom Properties überschrieben werden, beispielsweise:

```css
:root {
  --megaMenuNavBackground: #5f6f74;
  --megaMenuNavTextColor: #ffffff;
  --megaMenuPanelWidth: 1280px;
  --megaMenuZIndex: 6000;
}
```

## Cache

Das geladene Termset wird im `sessionStorage` des Browsers gespeichert. Der Schlüssel ist mit `MegaMenu:TermSet:` namensräumlich getrennt. Nach Ablauf von `cacheMinutes` wird das Termset automatisch neu geladen.

Für einen sofortigen administrativen Test kann der Session-Cache in den Browser-Entwicklertools gelöscht oder ein neues privates Browserfenster verwendet werden.

## Barrierefreiheit

- semantisches `<nav aria-label="Hauptnavigation">`
- native Listen- und Linksemantik
- `aria-expanded` und `aria-haspopup` für aufklappbare Einträge
- `aria-current="page"` für den aktuellen Navigationspfad
- Öffnen über Leertaste oder Pfeil nach unten
- Schließen über Escape
- sichtbare Fokusindikatoren
- Unterstützung von `prefers-reduced-motion` und kontrastreichen Darstellungen

Bewusst wird kein `role="menubar"` verwendet: Eine Portalnavigation ist eine normale Navigation und kein Desktop-Menü-Widget. Dadurch bleiben native Browser- und Screenreader-Erwartungen erhalten.

## Fehlerdiagnose

### „Die Navigation ist nicht konfiguriert“

Weder eine gültige `termSetId` noch ein `termSetName` ist gesetzt. UserCustomAction beziehungsweise PortalSettings-Konfiguration prüfen.

### „Die Navigation konnte nicht geladen werden“

- Existiert das Termset im Standard-Term-Store der Site Collection?
- Ist die GUID korrekt?
- Haben Benutzer Zugriff auf den Managed-Metadata-Service?
- Enthält das Termset mindestens einen sichtbaren Term?
- Ist der App-Catalog-Eintrag aktuell?

Für weitere technische Details kann vorübergehend `debug: true` gesetzt werden.

### Änderungen am Termset erscheinen verzögert

Die Navigation wird bis zu `cacheMinutes` im Session-Cache gehalten. Cache leeren oder Ablaufzeit abwarten.

### Zusätzliches CSS wird nicht geladen

- URL und Dateiberechtigungen prüfen.
- Für externe Quellen HTTPS verwenden.
- Browser-Konsole bei aktiviertem Debug-Modus prüfen.

## Upgrade von 1.0.x

- Bestehende `termSetName`-Konfigurationen funktionieren unverändert.
- Der alte unversionierte Session-Cache wird nicht weiterverwendet.
- `cacheMinutes` verwendet ohne Konfiguration den Wert 15.
- Die eigene, nicht verwendete MegaMenu-Einstellungsseite wurde entfernt; PortalSettings ist der zentrale Konfigurationsweg.
- Globale Event Listener werden beim Dispose der Extension entfernt.
- Paket-, npm- und Dokumentationsversion wurden auf 1.1.0 vereinheitlicht.

## Classic Pages

Unter `classic/` befindet sich eine separate Kompatibilitätsimplementierung für klassische SharePoint-Seiten. Sie wird nicht vom SPFx-Bundle ausgeführt und besitzt einen eigenen Deploymentweg. Neue Funktionen sollten zuerst in der modernen SPFx-Variante umgesetzt und anschließend bewusst in die Classic-Variante übernommen werden.

## Projektstruktur

```text
MegaMenu/
├── config/                         SPFx-Build- und Paketkonfiguration
├── deployment/                     Farm-/Site-Registrierung
├── src/
│   ├── extensions/megaMenu/        Application Customizer und Renderer
│   └── services/                    Taxonomy- und Datenmodelle
├── classic/                        optionale Classic-Kompatibilität
├── build-classic.ps1               Classic-Build
├── gulpfile.js
└── package.json
```

## Versionshistorie

### 1.1.0

- konsistente Verwendung des Default Site Collection Term Store
- optionale Konfiguration per Termset-GUID
- Cache-TTL und namensräumlich getrennter Session-Cache
- korrekte Anwendung der Deprecated-/Availability-Filter
- Prüfung der Taxonomy-HTTP-Antworten
- Lifecycle-Cleanup für globale Event Listener
- korrigierte Navigationssemantik und aktive Screenreader-Statusmeldungen
- Validierung externer CSS-URLs
- sichtbare Konfigurations- und Ladefehler
- Entfernung des ungenutzten lokalen Settings-Panels
- vereinheitlichte Projektversion und neue Build-/Deployment-Dokumentation