Client/ios/TimetableWidgetExtension/SETUP.md

iOS Widget Extension — Xcode Setup

Die Swift-Quellen unter ios/TimetableWidgetExtension/ müssen einmalig in Xcode als Widget Extension Target verdrahtet werden — ohne diesen Schritt bleibt der Code unkompiliert.

Schritt 1 — Widget-Extension-Target anlegen

1. ios/Runner.xcworkspace in Xcode öffnen.
2. Projekt-Sidebar → Runner (Projekt-Root) → + Add Target unten links.
3. iOS → Widget Extension wählen.
4. Eigenschaften:
   • Product Name: TimetableWidgetExtension
   • Bundle Identifier: eu.mhsl.marianum.mobile.client.TimetableWidgetExtension
   • Language: Swift
   • Include Configuration Intent: OFF (StaticConfiguration reicht)
   • Embed in: Runner
5. Beim Activate-Scheme-Dialog auf Cancel klicken.

Schritt 2 — Vorhandene Quelldateien ins Target ziehen

Xcode hat zunächst Dummy-Dateien (TimetableWidgetExtension.swift, TimetableWidgetExtensionBundle.swift) angelegt. Diese löschen (Move to Trash). Dann:

1. Sidebar → Rechtsklick auf den Ordner TimetableWidgetExtension → Add Files to "Runner"…
2. Im File-Picker zu ios/TimetableWidgetExtension/ navigieren und alle .swift-Dateien, die Info.plist, TimetableWidgetExtension.entitlements und den Assets.xcassets-Ordner selektieren (mit marianum_m-Asset darin — gleicher Asset-Name wie auf Android-Seite).
3. Wichtig: bei „Add to targets" nur TimetableWidgetExtension ankreuzen, nicht Runner.

Schritt 3 — App Group aktivieren

Beide Targets brauchen die App-Group-Berechtigung, damit Hauptapp und Widget über UserDefaults(suiteName:) schreiben/lesen können.

1. Runner-Target → Signing & Capabilities → + Capability → App Groups.
   • Group-ID hinzufügen: group.eu.mhsl.marianum.mobile.client.widget
2. Dasselbe für TimetableWidgetExtension — mit derselben Group-ID.

Im Apple-Developer-Portal muss die App-Group bei beiden App-IDs eingetragen sein, sonst schlägt das Provisioning fehl.

Schritt 4 — Entitlements verlinken

1. Runner → Build Settings → CODE_SIGN_ENTITLEMENTS sollte bereits auf Runner/Runner.entitlements zeigen.
2. TimetableWidgetExtension → Build Settings → CODE_SIGN_ENTITLEMENTS → auf TimetableWidgetExtension/TimetableWidgetExtension.entitlements setzen.

Schritt 5 — Info.plist + Deployment Target

1. TimetableWidgetExtension → Build Settings → INFOPLIST_FILE → auf TimetableWidgetExtension/Info.plist setzen.
2. Build Settings → IPHONEOS_DEPLOYMENT_TARGET ≥ 16.0 (Code gated .containerBackground mit if #available(iOS 17, *), läuft also auch auf 16).

Schritt 6 — Build & Run

• Scheme Runner (nicht das Widget-Scheme) wählen → Run.
• Auf Home-Screen langes Drücken → Widget hinzufügen → "Marianum · Heute" / "Marianum · Woche".
• Widget-Tap öffnet die App im zuletzt sichtbaren Tab. Eine Tab-Navigation auf den Stundenplan ist bewusst nicht implementiert (Android nutzt Intent-Extras, iOS würde dafür ein URL-Scheme oder AppIntent brauchen — beides bewusst ausgespart).

Troubleshooting

• Widget zeigt „Lade…" auch nach Refresh: App-Group greift nicht. Prüfen, ob beide Targets dieselbe Group-ID haben und das Provisioning aktualisiert wurde.
• Stale-Daten nach Logout: WidgetSync.clear() schreibt widget_data_logged_in_v1 = false; Widget zeigt dann den Login-Placeholder.
• Lessons um 1–2 Stunden verschoben: Date-Parser-Bug. Sollte gefixt sein in WidgetData.swift::parseDartDate — verifizieren, dass die ISO-8601-Strings ohne Z-Suffix als TimeZone.current geparsed werden.
• App-Store-Submit später: Runner.entitlements aps-environment von development auf production umbiegen.

Was bereits im Repo erledigt ist

• Alle Swift-Quellen, Info.plist, Entitlements liegen unter ios/TimetableWidgetExtension/.
• App-Group-ID konsistent zwischen Dart (WidgetSync.iosAppGroupId), Swift (WidgetDataKey.appGroupId) und der Entitlements-Datei.
• home_widget-Plugin auf der Dart-Seite konfiguriert; ruft HomeWidget.setAppGroupId beim ersten Sync.
• containerBackground für iOS 17+ gegated, fällt auf iOS 16 sauber zurück.
• Date-Parser fixt das fehlende Z-Suffix (Dart schreibt lokale Zeit ohne TZ-Marker).

Was am Mac noch zu tun ist

• Schritte 1–5 oben in Xcode durchklicken (10–15 Min).
• flutter pub get + cd ios && pod install.
• Auf physischem Gerät oder iOS-Simulator (≥ 16.0) bauen.
• Widget aufs Home-Screen ziehen, prüfen dass Lesson-Zeiten korrekt rendern.