mana-swift-ui/CLAUDE.md

CLAUDE.md — mana-swift-ui

Guidance für Claude Code in diesem Repo.

Übergeordneter Plan: ../mana/docs/MANA_SWIFT.md ist die SOT für die ganze native-App-Plattform. Phase ε dort beschreibt dieses Paket.

Was dieses Repo ist

Swift-Package mit native UI-Komponenten für alle nativen mana-e.V.-Apps. Drei Library-Products:

• ManaAuthUI — vollständige Auth-Reise als SwiftUI-Views: Login, Sign-Up, Email-Verifikation, Passwort-Reset, Account-Management. Konsumiert ManaCore (für API-Calls) und ManaTokens (für Vereins-Designwerte). Breit konsumiert (memoro, seepuls, mukke, herbatrium, …).
• ManaWebShell — dünne WKWebView-Hülle (WebShellView + WebShellConfig + WebShellScripts) zum Anzeigen einer Web-App in einer nativen Schale. Siehe Retention-Hinweis unten.
• ManaLLMUI — Settings-UI für lokale LLMs (konsumiert ManaLLM).

ManaWebShell — bewusst behalten, aktuell ohne Konsument

Stand 2026-05-25: ManaWebShell hat null Konsumenten. Die beiden Hybrid-Apps wurden voll nativ (zitare η-0..η-9, seepuls σ-7); mukkes toter Dependency-Eintrag wurde entfernt.

Wir behalten das Paket trotzdem — Entscheidung Till, 2026-05-25. Begründung: Es ist der naheliegende Baustein, um eine neue App schnell als Hybrid zu starten (Web-App in nativer Schale + Widget/ Share/Universal-Links), bevor sie — wenn sie sich bewährt — schrittweise nativ wird. Genau diesen Weg sind zitare und seepuls gegangen. Das Paket ist getestet (ManaWebShellTests), pure SwiftUI/WKWebView, ohne Laufzeitkosten solange es niemand importiert.

Wenn du eine neue App schnell bootstrappen willst: ManaWebShell als Dependency ziehen, WebShellView(target:config:) in einen Tab, WebShellConfig mit allowedHosts + userScripts (z.B. preferDarkScheme, hideElements) konfigurieren. Vorbild-Pattern (vor der De-Hybridisierung): seepuls-native Git-History vor σ-7 bzw. zitare-native vor η-0.

Beim Entfernen (falls je beschlossen): Library-Target + ManaWebShellTests aus Package.swift, dann prüfen dass swift build sauber bleibt.

Status

v0.1.0 — initiale Extraktion 2026-05-13.

Phase 2 aus dem Native-Auth-Vollausbau-Plan (Option A — alles nativ). Entstanden weil drei Apps fast-byte-identische LoginView.swift- Dateien hatten und Sign-Up/Forgot-PW komplett fehlten.

Architektonische Invarianten

Nicht ohne explizite Diskussion antasten:

1. Keine externen UI-Libraries. Pure SwiftUI. Identische Regel wie in ManaCore (mana-swift-core/CLAUDE.md Invariante 2).
2. App injiziert ManaBrandConfig. Keine hardcoded Farben oder App-Namen im Paket. forest/mana/zukünftige Themes leben in der App, nicht hier — bis ManaTokens-Theme-Variants kommen.
3. ViewModels sind testbar, Views sind dünn. Jede non-triviale View hat einen begleitenden @Observable-ViewModel mit reiner State-Maschine. URLProtocol-Mock-Tests gehen gegen ViewModels.
4. Lokalisierung DE first. Public-API-Strings auf Deutsch, EN später via Localizable.xcstrings. Konsistent mit Verein-Konvention.
5. Account-Löschung ist Pflicht-Komponente. App-Store-Guideline 5.1.1(v) — ManaDeleteAccountView MUSS in jeder App, die ManaSignUpView einbaut, erreichbar sein.
6. iOS 18 / macOS 15. Gleiche Minimums wie mana-swift-core.
7. Public API ist Sendable. Swift-6-Strict-Concurrency.

Repo-Layout

mana-swift-ui/
├── Package.swift
├── README.md
├── CHANGELOG.md
├── CLAUDE.md                    dieses File
├── Sources/
│   ├── ManaAuthUI/
│   │   ├── Brand/               ManaBrandConfig (App-injiziert)
│   │   ├── Components/          ManaAuthScaffold, ManaTextField, ...
│   │   ├── Login/               ManaLoginView + ViewModel
│   │   ├── Register/            ManaSignUpView + ViewModel
│   │   ├── Verify/              ManaEmailVerifyGateView
│   │   ├── Reset/               ManaForgotPasswordView, ManaResetPasswordView
│   │   └── Account/             ChangeEmail/ChangePassword/DeleteAccount
│   ├── ManaWebShell/           WebShellView + WebShellConfig + WebShellScripts
│   │                           (Hybrid-Scaffold, aktuell ohne Konsument)
│   └── ManaLLMUI/              Lokal-LLM-Settings-UI
└── Tests/
    ├── ManaAuthUITests/
    └── ManaWebShellTests/

Konventionen

• Swift 6.0, Strict Concurrency komplett
• iOS 18 / macOS 15 Minimum
• Tabs für Indent? Nein — wir nutzen 4 Spaces wie mana-swift-core (SwiftFormat .swiftformat). Verein-TS-Repos nutzen Tabs, Swift-Repos Spaces — bewusster Bruch wegen Xcode-Tooling
• Doc-Comments pflicht auf jedem public-Symbol (///)
• Lokalisierung: Public-API-Strings auf Deutsch

Versionierung

• Semver strikt. UI ändert sich öfter als Auth-Core — getrenntes Repo damit mana-swift-core stabil bleibt
• CHANGELOG.md pflicht. Was hat sich geändert, müssen Apps was anpassen
• Pflege-Politik: Letzte zwei Minor-Versionen mit Patches

Lokal entwickeln

swift build              # baut ManaAuthUI
swift test               # Unit-Tests gegen ViewModels

mana-swift-core muss als Schwester-Verzeichnis existieren.

Wenn ein neuer Auth-Flow dazukommt

1. ViewModel zuerst — pure State-Maschine, testbar
2. SwiftUI-View dünn, nur @Observable-State-Bindings
3. Public-API-Doc auf Deutsch
4. ViewModel-Tests via URLProtocol-Mock (Pattern in ManaAuthUITests/)
5. CHANGELOG.md ergänzen
6. Bei Breaking-Change: Major-Bump-Plan + alle aktiven Apps informieren

Wichtige Cross-Repo-Doks

• ../mana/docs/MANA_SWIFT.md — Plattform-SOT, Phase ε
• ../mana-swift-core/CLAUDE.md — Auth-Core, ManaTokens
• ../mana/docs/THEMING.md — Token-SOT, spiegelt sich in ManaTokens
• ../mana/services/mana-auth/CLAUDE.md — Server-Konventionen