+
+> Dies ist eine Übersetzung der englischen README. Bei Abweichungen gilt die englische Fassung.
+
+
+
+WidgetDevelopmentKit ist ein Swift-Paket für alle, die Widgets für ihre iOS-Apps bauen. Es
+enthält fertige SwiftUI-Views für Widgets auf dem Home-Bildschirm, dem Sperrbildschirm und in
+StandBy, Diagramm-Views in Widget-Größe, Hilfstypen für Timelines und für die Daten, die die
+App mit ihrem Widget teilt, App Intents für Widget-Buttons sowie ActivityKit-Attribute und
+-Views für Live Activities. Die Widget-Extension schreibst du weiterhin selbst; das Paket nimmt
+dir die Views und die Datums-, Speicher- und Wiederholungslogik ab, die jedes Widget braucht.
+
+## Highlights
+
+- **20 Vorlagen für den Home-Bildschirm** – Wetter, Statistiken, Finanzen, Kalender,
+ Countdown, Uhr, Notizen, Zitate, Musik, Podcast, Nachrichten, Fitnessringe,
+ Gewohnheitstracker, To-dos, Wasser, Batterie und mehr.
+- **Sperrbildschirm und StandBy** – 15 Accessory-Views (kreisförmig, rechteckig, inline) und 7
+ StandBy-Views.
+- **Timeline-Hilfen** – Eintragsdaten, Reload-Richtlinien und ein Snapshot-Speicher mit
+ Ablaufzeit, damit das Widget liest, was die App über eine App Group gespeichert hat.
+- **Interaktive Widgets** – 5 App Intents und 8 Views mit Buttons, die sie ausführen.
+- **Live Activities** – 10 `ActivityAttributes`-Typen mit Views für den Sperrbildschirm und
+ die kompakte Dynamic Island sowie ein Zustandsautomat, der Updates in falscher Reihenfolge
+ ablehnt.
+- **Getestete Logik** – der Code für Datumswerte, Zahlen und Wiederholungen ist mit Swift
+ Testing getestet, auch für Grenzfälle wie `NaN`, Ziele von null und Tage mit
+ Zeitumstellung.
+
+## Schnellstart
+
+**1. Paket hinzufügen**
+
+Deine App braucht eine Widget-Extension. Falls es noch keine gibt, wähle in Xcode **File ›
+New › Target…** und dann **Widget Extension**. Wähle anschließend **File › Add Package
+Dependencies…**, füge diese URL oben rechts in das Suchfeld ein und klicke auf **Add
+Package**:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Stelle im nächsten Dialog in der Spalte **Add to Target** für `WidgetDevelopmentKit` deine
+Widget-Extension ein und klicke auf **Add Package**.
+
+**2. Modul importieren**
+
+Am Anfang einer Swift-Datei der Widget-Extension:
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. Verwenden**
+
+Füge dieses Widget zur Extension hinzu. Es zählt mit der `CountdownWidget`-View des Pakets
+bis zu einem Datum herunter. Trage danach `LaunchCountdownWidget()` im `WidgetBundle` der
+Extension ein, also im Typ, der mit `@main` markiert ist.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Starte die App in einem iPhone-Simulator. Halte auf dem Home-Bildschirm eine freie Stelle
+gedrückt, tippe auf **Edit › Add Widget**, suche deine App und füge **Countdown** hinzu.
+Derselbe Code steht in
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
+
+## Installation
+
+### Swift Package Manager
+
+Wähle in Xcode **File › Add Package Dependencies…** und gib die Repository-URL ein:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Oder füge es zu den `dependencies` in deiner `Package.swift` hinzu:
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+Releases beginnen mit 2.0.0; das frühere Tag `v1.0.0` ist älter als der aktuelle Code und
+lässt sich nicht bauen. Das Paket hat keine Abhängigkeiten von Drittanbietern.
+
+## Verwendung
+
+Alle Swift-Beispiele in diesem Abschnitt stammen aus
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), das CI baut, oder aus
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift), das
+mit den Tests kompiliert wird. Ein Test schlägt fehl, wenn ein Block hier nicht mehr mit diesem
+Code übereinstimmt.
+
+### Geteilte Daten in einem Timeline-Provider lesen
+
+`TimelineSchedule` erzeugt die Eintragsdaten, `TimelineBuilder` sortiert die Einträge und
+übersetzt eine `WidgetUpdatePolicy` in die Reload-Richtlinie von WidgetKit, und
+`WidgetSnapshotStore` liest, was die App in der gemeinsamen App Group gespeichert hat.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Daten in der App speichern
+
+Die App schreibt den Wert mit einer Gültigkeitsdauer und bittet WidgetKit, das Widget neu zu
+laden:
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Füge der App und der Extension die Capability **App Groups** mit derselben Kennung hinzu. Der
+Speicher nutzt `UserDefaults`, das nicht verschlüsselt ist; lege dort also keine Geheimnisse
+ab.
+
+### Einen Eintrag anzeigen
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Views, die zeitabhängige Werte zeigen (`CountdownWidget`, `StandByCountdownWidget`,
+`LockScreenCountdownWidget`), erhalten ein `referenceDate`; übergib `entry.date`, damit jeder
+Eintrag seinen eigenen Zeitpunkt darstellt.
+
+### Einem Widget einen Button hinzufügen
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Die Intents laufen in der Widget-Extension und schreiben in `WidgetStateStore.shared`. Dieser
+Speicher verwendet die App Group, die im Schlüssel `WidgetDevelopmentKitAppGroup` der
+Info.plist steht. Trage den Schlüssel in der App und in der Extension ein und registriere die
+Intents des Pakets:
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Daten von einem Server laden
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader` verwendet eine flüchtige (ephemeral) Session mit kurzen Timeouts, die nicht
+auf eine Verbindung wartet. Er wiederholt Antworten mit 5xx und 408, Timeouts und
+Offline-Fehler (standardmäßig einmal; mit einer `RetryPolicy` änderbar), aber keine
+4xx-Antworten oder Decodierungsfehler.
+
+## Demo
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Die Bilder werden von [`scripts/render-screenshots.sh`](scripts/render-screenshots.sh) mit
+`ImageRenderer` aus den Views des Pakets gerendert. Da sie außerhalb von WidgetKit entstehen,
+sind Widget-Rahmen, Sperrbildschirm-Vibrancy und der Nachtmodus von StandBy nur angenähert und
+nicht vom System erzeugt.
+
+Um die Widgets selbst auszuprobieren, öffne
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) und starte
+das Schema **WidgetKitExample** in einem iPhone-Simulator;
+[`Examples/README.md`](Examples/README.md) beschreibt die drei Widgets und wie du sie zum
+Home-Bildschirm hinzufügst.
+
+## Dokumentation
+
+API-Referenz und Artikel:
+
+- [API-Referenz](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ auf GitHub Pages, erzeugt aus den DocC-Kommentaren im Quellcode.
+- In Xcode: **Product › Build Documentation**, oder
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Anleitungen
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ Widget-Extension und Paket hinzufügen, Daten über eine App Group teilen, die Timeline
+ aufbauen und einen Eintrag darstellen.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ App Group einrichten, Intents registrieren, Buttons hinzufügen und ihren Zustand im Provider
+ und in der App lesen.
+
+## Voraussetzungen
+
+| Plattform | Mindestversion |
+| --------- | -------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Toolchain | Swift 6.0 |
+
+Sperrbildschirm-Views und Live Activities gibt es nur unter iOS. Das macOS-Ziel existiert,
+damit der plattformunabhängige Code und seine Tests mit `swift test` laufen. CI baut mit dem
+Standard-Xcode des `macos-26`-Images von GitHub; lokal wird mit Xcode 27 entwickelt. Ältere
+Xcode-Versionen wurden nicht ausprobiert.
+
+## Architektur
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+Die Views bleiben schlank: Berechnungen, die mit echten Daten schiefgehen können (Ziele von
+null, `NaN`, vertauschte Datumsbereiche, Tage mit Zeitumstellung), liegen als reine Funktionen
+mit Unit-Tests in `Core` und `Timeline`. Typen, die auf Speicher oder Netzwerk zugreifen,
+erhalten ihre Abhängigkeiten (`UserDefaults`, Uhr, Transport, Warten) als Parameter und lassen
+sich so ohne App Group oder Server testen. Für die Bodies der SwiftUI-Views gibt es keine
+Snapshot-Tests.
+
+Führe die Tests unter macOS und in einem iOS-Simulator aus:
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Drei iOS-Tests werden absichtlich übersprungen: Sie rendern die Bilder der README und laufen nur
+über `scripts/render-screenshots.sh`.
+
+## Roadmap
+
+- Ein Release taggen, das zum aktuellen Code passt, damit sich das Paket per Version einbinden
+ lässt.
+- Snapshot-Tests für die View-Bodies.
+- Eine Beispiel-Live-Activity in der Beispiel-App.
+
+Das [CHANGELOG](CHANGELOG.md) hält fest, was sich bisher geändert hat, auch wie das Paket im
+Oktober 2026 wiederhergestellt wurde, nachdem sich herausgestellt hatte, dass der Code von
+`v1.0.0` nicht baut.
+
+## Mitwirken
+
+Beiträge sind willkommen. Lies vor einem Pull Request den [Leitfaden für Beiträge](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) und den [Verhaltenskodex](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md). Sicherheitsprobleme meldest du vertraulich, wie in der [Sicherheitsrichtlinie](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md) beschrieben.
+
+## Lizenz
+
+Veröffentlicht unter der MIT-Lizenz. Siehe [LICENSE](LICENSE).
diff --git a/README.es.md b/README.es.md
new file mode 100644
index 0000000..303c98d
--- /dev/null
+++ b/README.es.md
@@ -0,0 +1,376 @@
+
+
+
+
+
+> Esta es una traducción del README en inglés. Si hay diferencias, la versión en inglés es la vigente.
+
+
+
+WidgetDevelopmentKit es un paquete Swift para quienes crean widgets para sus apps de iOS.
+Incluye vistas SwiftUI listas para usar en widgets de la pantalla de inicio, la pantalla
+bloqueada y StandBy, vistas de gráficos adaptadas al tamaño de un widget, utilidades para las
+líneas de tiempo y para los datos que la app comparte con su widget, App Intents para los
+botones de los widgets, y atributos y vistas de ActivityKit para Live Activities. La extensión
+de widgets la sigues escribiendo tú; el paquete te ahorra las vistas y la lógica de fechas,
+almacenamiento y reintentos que necesita cualquier widget.
+
+## Lo más destacado
+
+- **20 plantillas para la pantalla de inicio**: tiempo, estadísticas, finanzas, calendario,
+ cuenta atrás, reloj, notas, citas, música, pódcast, noticias, anillos de actividad física,
+ seguimiento de hábitos, tareas, agua, batería y más.
+- **Pantalla bloqueada y StandBy**: 15 vistas accesorias (circular, rectangular, en línea) y 7
+ vistas de StandBy.
+- **Utilidades de línea de tiempo**: fechas de las entradas, políticas de recarga y un almacén
+ de instantáneas con caducidad, para que el widget lea lo que la app guardó a través de un
+ App Group.
+- **Widgets interactivos**: 5 App Intents y 8 vistas con botones que los ejecutan.
+- **Live Activities**: 10 tipos de `ActivityAttributes` con vistas para la pantalla bloqueada y
+ la Dynamic Island compacta, y una máquina de estados que rechaza las actualizaciones que
+ llegan desordenadas.
+- **Lógica con pruebas**: el código de fechas, números y reintentos está cubierto por pruebas
+ de Swift Testing, incluidos casos límite como `NaN`, objetivos de cero y los días de cambio
+ de horario.
+
+## Inicio rápido
+
+**1. Añade el paquete**
+
+Tu app necesita una extensión de widgets. Si todavía no tiene una, elige **File › New ›
+Target…** en Xcode y selecciona **Widget Extension**. Después elige **File › Add Package
+Dependencies…**, pega esta URL en el campo de búsqueda de la esquina superior derecha y pulsa
+**Add Package**:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+En el siguiente cuadro de diálogo, en la columna **Add to Target** de `WidgetDevelopmentKit`
+elige tu extensión de widgets y pulsa **Add Package**.
+
+**2. Importa el módulo**
+
+Al principio de un archivo Swift de la extensión de widgets:
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. Úsalo**
+
+Añade este widget a la extensión. Muestra una cuenta atrás hasta una fecha con la vista
+`CountdownWidget` del paquete. Después incluye `LaunchCountdownWidget()` en el `WidgetBundle`
+de la extensión, el tipo marcado con `@main`.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Ejecuta la app en un simulador de iPhone. En la pantalla de inicio, mantén pulsada una zona
+vacía, toca **Edit › Add Widget**, busca tu app y añade **Countdown**. El mismo código está en
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
+
+## Instalación
+
+### Swift Package Manager
+
+En Xcode, elige **File › Add Package Dependencies…** e introduce la URL del repositorio:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+O añádelo a las `dependencies` de tu `Package.swift`:
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+Las versiones empiezan en 2.0.0; la etiqueta anterior, `v1.0.0`, es anterior al código
+actual y no compila. El paquete no tiene dependencias de terceros.
+
+## Uso
+
+Todos los ejemplos de Swift de esta sección salen de
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), que CI compila, o de
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift), que
+se compila con las pruebas. Si un bloque de aquí deja de coincidir con ese código, falla una
+prueba.
+
+### Leer datos compartidos en un proveedor de línea de tiempo
+
+`TimelineSchedule` genera las fechas de las entradas, `TimelineBuilder` ordena las entradas y
+convierte una `WidgetUpdatePolicy` en la política de recarga de WidgetKit, y
+`WidgetSnapshotStore` lee lo que la app guardó en el App Group compartido.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Guardar datos en la app
+
+La app escribe el valor con un tiempo de validez y pide a WidgetKit que recargue el widget:
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Añade la capacidad **App Groups** a la app y a la extensión con el mismo identificador. El
+almacén usa `UserDefaults`, que no está cifrado, así que no guardes en él datos secretos.
+
+### Mostrar una entrada
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Las vistas que muestran valores que dependen del tiempo (`CountdownWidget`,
+`StandByCountdownWidget`, `LockScreenCountdownWidget`) reciben un `referenceDate`; pasa
+`entry.date` para que cada entrada muestre su propio momento.
+
+### Añadir un botón a un widget
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Los intents se ejecutan en la extensión de widgets y escriben en `WidgetStateStore.shared`,
+que usa el App Group indicado en la clave `WidgetDevelopmentKitAppGroup` de Info.plist. Añade
+la clave tanto a la app como a la extensión y registra los intents del paquete:
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Cargar datos de un servidor
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader` usa una sesión efímera con tiempos de espera cortos que no espera a que haya
+conexión. Reintenta las respuestas 5xx y 408, los tiempos de espera agotados y los errores sin
+conexión (una vez por defecto; configura una `RetryPolicy` para cambiarlo), pero no las
+respuestas 4xx ni los errores de decodificación.
+
+## Demo
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Las imágenes se dibujan a partir de las vistas del paquete con `ImageRenderer` mediante
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh). Como se dibujan fuera de
+WidgetKit, el marco del widget, la vibrancia de la pantalla bloqueada y el modo nocturno de
+StandBy son una aproximación y no los genera el sistema.
+
+Para probar los widgets, abre
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) y ejecuta
+el esquema **WidgetKitExample** en un simulador de iPhone;
+[`Examples/README.md`](Examples/README.md) explica los tres widgets y cómo añadirlos a la
+pantalla de inicio.
+
+## Documentación
+
+Referencia de la API y artículos:
+
+- [Referencia de la API](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ en GitHub Pages, generada a partir de los comentarios DocC del código.
+- En Xcode: **Product › Build Documentation**, o
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Guías
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ añadir una extensión de widgets y el paquete, compartir datos mediante un App Group, crear la
+ línea de tiempo y dibujar una entrada.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ configurar el App Group, registrar los intents, añadir botones y leer su estado en el
+ proveedor y en la app.
+
+## Requisitos
+
+| Plataforma | Versión mínima |
+| ------------ | -------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Herramientas | Swift 6.0 |
+
+Las vistas de la pantalla bloqueada y las Live Activities solo existen en iOS. El destino de
+macOS está para que el código independiente de la plataforma y sus pruebas se ejecuten con
+`swift test`. CI compila con el Xcode predeterminado de la imagen `macos-26` de GitHub; el
+desarrollo local usa Xcode 27. No se han probado versiones anteriores de Xcode.
+
+## Arquitectura
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+Las vistas son finas: los cálculos que pueden fallar con datos reales (objetivos de cero,
+`NaN`, rangos de fechas invertidos, días de cambio de horario) están en `Core` y `Timeline` como
+funciones puras con pruebas unitarias. Los tipos que acceden al almacenamiento o a la red
+reciben sus dependencias (`UserDefaults`, reloj, transporte, espera) como parámetros, así que se
+pueden probar sin un App Group ni un servidor. Los cuerpos de las vistas SwiftUI no tienen
+pruebas de instantáneas.
+
+Ejecuta las pruebas en macOS y en un simulador de iOS:
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Tres pruebas de iOS se omiten a propósito: dibujan las imágenes del README y solo se ejecutan
+mediante `scripts/render-screenshots.sh`.
+
+## Hoja de ruta
+
+- Etiquetar una versión que corresponda al código actual, para poder añadir el paquete por
+ versión.
+- Pruebas de instantáneas para los cuerpos de las vistas.
+- Una Live Activity de ejemplo en la app de ejemplo.
+
+El [CHANGELOG](CHANGELOG.md) recoge los cambios hasta ahora, incluido cómo se restauró el
+paquete en octubre de 2026 después de comprobar que el código de `v1.0.0` no compilaba.
+
+## Contribuir
+
+Las contribuciones son bienvenidas. Lee la [guía de contribución](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) y el [código de conducta](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) antes de abrir una pull request. Informa de los problemas de seguridad de forma privada, como se describe en la [política de seguridad](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md).
+
+## Licencia
+
+Publicado bajo la licencia MIT. Consulta [LICENSE](LICENSE).
diff --git a/README.fr.md b/README.fr.md
new file mode 100644
index 0000000..b9deba8
--- /dev/null
+++ b/README.fr.md
@@ -0,0 +1,379 @@
+
+
+
+
+
+> Ceci est une traduction du README anglais. En cas de différence, la version anglaise fait foi.
+
+
+
+WidgetDevelopmentKit est un paquet Swift destiné aux développeurs qui créent des widgets pour
+leurs apps iOS. Il contient des vues SwiftUI prêtes à l’emploi pour les widgets de l’écran
+d’accueil, de l’écran verrouillé et de StandBy, des vues de graphiques adaptées à la taille
+d’un widget, des utilitaires pour les timelines et pour les données que l’app partage avec son
+widget, des App Intents pour les boutons des widgets, ainsi que des attributs et des vues
+ActivityKit pour les Live Activities. Vous écrivez toujours l’extension de widget vous-même ;
+le paquet vous épargne les vues et la logique de dates, de stockage et de nouvelles tentatives
+dont tout widget a besoin.
+
+## Points forts
+
+- **20 modèles pour l’écran d’accueil** — météo, statistiques, finances, calendrier, compte à
+ rebours, horloge, notes, citation, musique, podcast, actualités, anneaux d’activité, suivi
+ d’habitudes, tâches, eau, batterie, etc.
+- **Écran verrouillé et StandBy** — 15 vues accessoires (circulaire, rectangulaire, en ligne)
+ et 7 vues StandBy.
+- **Utilitaires de timeline** — dates des entrées, politiques de rechargement et un stockage
+ d’instantanés avec expiration, pour que le widget lise ce que l’app a enregistré via un App
+ Group.
+- **Widgets interactifs** — 5 App Intents et 8 vues dont les boutons les exécutent.
+- **Live Activities** — 10 types `ActivityAttributes` avec des vues pour l’écran verrouillé et
+ la Dynamic Island compacte, et une machine à états qui rejette les mises à jour arrivées dans
+ le désordre.
+- **Logique testée** — le code des dates, des nombres et des nouvelles tentatives est couvert
+ par des tests Swift Testing, y compris des cas limites comme `NaN`, un objectif nul et les
+ jours de changement d’heure.
+
+## Démarrage rapide
+
+**1. Ajouter le paquet**
+
+Votre app a besoin d’une extension de widget. Si elle n’en a pas encore, choisissez **File ›
+New › Target…** dans Xcode, puis **Widget Extension**. Choisissez ensuite **File › Add Package
+Dependencies…**, collez cette URL dans le champ de recherche en haut à droite et cliquez sur
+**Add Package** :
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Dans la fenêtre suivante, réglez **Add to Target** de `WidgetDevelopmentKit` sur votre
+extension de widget, puis cliquez sur **Add Package**.
+
+**2. Importer le module**
+
+En haut d’un fichier Swift de l’extension de widget :
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. L’utiliser**
+
+Ajoutez ce widget à l’extension. Il affiche un compte à rebours jusqu’à une date avec la vue
+`CountdownWidget` du paquet. Ajoutez ensuite `LaunchCountdownWidget()` au `WidgetBundle` de
+l’extension, le type marqué `@main`.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Lancez l’app dans un simulateur d’iPhone. Sur l’écran d’accueil, maintenez le doigt sur une
+zone vide, touchez **Edit › Add Widget**, cherchez votre app et ajoutez **Countdown**. Le même
+code se trouve dans
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
+
+## Installation
+
+### Swift Package Manager
+
+Dans Xcode, choisissez **File › Add Package Dependencies…** et saisissez l’URL du dépôt :
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Ou ajoutez-le aux `dependencies` de votre `Package.swift` :
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+Les versions commencent à 2.0.0 ; l’ancien tag `v1.0.0` est antérieur au code actuel et
+ne compile pas. Le paquet n’a aucune dépendance tierce.
+
+## Utilisation
+
+Chaque exemple Swift de cette section provient de
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), que la CI compile, ou de
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift),
+compilé avec les tests. Un test échoue si un bloc de cette page ne correspond plus à ce code.
+
+### Lire des données partagées dans un fournisseur de timeline
+
+`TimelineSchedule` produit les dates des entrées, `TimelineBuilder` trie les entrées et
+convertit une `WidgetUpdatePolicy` en politique de rechargement de WidgetKit, et
+`WidgetSnapshotStore` lit ce que l’app a enregistré dans l’App Group partagé.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Enregistrer des données dans l’app
+
+L’app écrit la valeur avec une durée de validité et demande à WidgetKit de recharger le
+widget :
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Ajoutez la capacité **App Groups** à l’app et à l’extension avec le même identifiant. Le
+stockage utilise `UserDefaults`, qui n’est pas chiffré : n’y mettez aucun secret.
+
+### Afficher une entrée
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Les vues qui affichent des valeurs dépendant du temps (`CountdownWidget`,
+`StandByCountdownWidget`, `LockScreenCountdownWidget`) prennent un `referenceDate` ; passez
+`entry.date` pour que chaque entrée affiche son propre instant.
+
+### Ajouter un bouton à un widget
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Les intents s’exécutent dans l’extension de widget et écrivent dans `WidgetStateStore.shared`,
+qui utilise l’App Group indiqué par la clé `WidgetDevelopmentKitAppGroup` de l’Info.plist.
+Ajoutez la clé à l’app et à l’extension, et enregistrez les intents du paquet :
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Charger des données depuis un serveur
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader` utilise une session éphémère avec des délais d’attente courts, qui n’attend
+pas la connexion. Il relance les réponses 5xx et 408, les délais dépassés et les erreurs hors
+ligne (une fois par défaut ; modifiable avec une `RetryPolicy`), mais pas les réponses 4xx ni
+les erreurs de décodage.
+
+## Démo
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Les images sont dessinées à partir des vues du paquet avec `ImageRenderer` par
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh). Comme elles sont dessinées en
+dehors de WidgetKit, le cadre du widget, la vibrance de l’écran verrouillé et le mode nuit de
+StandBy sont approximés et non produits par le système.
+
+Pour essayer les widgets vous-même, ouvrez
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) et lancez
+le schéma **WidgetKitExample** dans un simulateur d’iPhone ;
+[`Examples/README.md`](Examples/README.md) présente les trois widgets et explique comment les
+ajouter à l’écran d’accueil.
+
+## Documentation
+
+Référence de l’API et articles :
+
+- [Référence de l’API](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ sur GitHub Pages, générée à partir des commentaires DocC du code source.
+- Dans Xcode : **Product › Build Documentation**, ou
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Guides
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted) :
+ ajouter une extension de widget et le paquet, partager des données via un App Group,
+ construire la timeline et afficher une entrée.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets) :
+ configurer l’App Group, enregistrer les intents, ajouter des boutons et lire leur état dans
+ le fournisseur et dans l’app.
+
+## Prérequis
+
+| Plateforme | Version minimale |
+| --------------- | ---------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Chaîne d’outils | Swift 6.0 |
+
+Les vues de l’écran verrouillé et les Live Activities n’existent que sur iOS. La cible macOS
+permet d’exécuter le code indépendant de la plateforme et ses tests avec `swift test`. La CI
+compile avec le Xcode par défaut de l’image `macos-26` de GitHub ; le développement local
+utilise Xcode 27. Les versions plus anciennes de Xcode n’ont pas été essayées.
+
+## Architecture
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+Les vues restent légères : les calculs qui peuvent mal tourner avec des données réelles
+(objectifs nuls, `NaN`, plages de dates inversées, jours de changement d’heure) se trouvent dans
+`Core` et `Timeline` sous forme de fonctions pures testées. Les types qui touchent au stockage
+ou au réseau reçoivent leurs dépendances (`UserDefaults`, horloge, transport, attente) en
+paramètres, ce qui permet de les tester sans App Group ni serveur. Les corps des vues SwiftUI
+n’ont pas de tests d’instantanés.
+
+Lancez les tests sur macOS et dans un simulateur iOS :
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Trois tests iOS sont ignorés volontairement : ils dessinent les images du README et ne
+s’exécutent que via `scripts/render-screenshots.sh`.
+
+## Feuille de route
+
+- Taguer une version qui correspond au code actuel, pour pouvoir ajouter le paquet par
+ version.
+- Des tests d’instantanés pour les corps des vues.
+- Une Live Activity d’exemple dans l’app d’exemple.
+
+Le [CHANGELOG](CHANGELOG.md) consigne les changements jusqu’ici, y compris la façon dont le
+paquet a été restauré en octobre 2026 après avoir constaté que le code de `v1.0.0` ne compilait
+pas.
+
+## Contribuer
+
+Les contributions sont les bienvenues. Lisez le [guide de contribution](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) et le [code de conduite](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) avant d’ouvrir une pull request. Signalez les problèmes de sécurité en privé, comme indiqué dans la [politique de sécurité](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md).
+
+## Licence
+
+Publié sous licence MIT. Voir [LICENSE](LICENSE).
diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 0000000..238966f
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,314 @@
+
+
+
+
----
+
-## ⚡ Live Activities
+WidgetDevelopmentKit is a Swift package for developers who build widgets for their iOS apps.
+It contains ready-made SwiftUI views for Home Screen, Lock Screen and StandBy widgets, chart
+views sized for widgets, helpers for timelines and for the data the app shares with its
+widget, App Intents for widget buttons, and ActivityKit attributes and views for Live
+Activities. You still write the widget extension; the package saves you the views and the
+date, storage and retry logic that every widget needs.
-### 10 Live Activity Templates
+## Highlights
-| Template | Use Case |
-|----------|----------|
-| `DeliveryActivity` | Food/package delivery |
-| `RideActivity` | Uber/Lyft style rides |
-| `SportsScoreActivity` | Live sports scores |
-| `TimerActivity` | Countdown timer |
-| `WorkoutActivity` | Fitness tracking |
-| `NowPlayingActivity` | Music player |
-| `FlightActivity` | Flight tracking |
-| `ParkingActivity` | Parking meter |
-| `OrderActivity` | Order status |
-| `MeetingActivity` | Calendar meetings |
+- **20 Home Screen templates** — weather, stats, finance, calendar, countdown, clock, notes,
+ quote, music, podcast, news, fitness rings, habit tracker, to-do, water, battery and more.
+- **Lock Screen and StandBy** — 15 accessory views (circular, rectangular, inline) and 7
+ StandBy views.
+- **Timeline helpers** — entry dates, reload policies and a snapshot store with expiry, so
+ the widget reads what the app saved through an App Group.
+- **Interactive widgets** — 5 App Intents and 8 views with buttons that run them.
+- **Live Activities** — 10 `ActivityAttributes` types with Lock Screen and compact Dynamic
+ Island views, and a state machine that rejects out-of-order updates.
+- **Tested logic** — the date, number and retry code is covered by Swift Testing tests,
+ including edge cases such as `NaN`, zero goals and daylight-saving days.
-### Create a Live Activity
+## Quick start
-```swift
-import ActivityKit
-import iOSWidgetKit
-
-// Define your activity
-let attributes = DeliveryAttributes(
- orderNumber: "12345",
- restaurantName: "Pizza Place"
-)
-
-let state = DeliveryAttributes.ContentState(
- status: .onTheWay,
- estimatedArrival: Date().addingTimeInterval(1800),
- driverName: "John",
- currentStep: 2
-)
-
-// Start the activity
-let activity = try LiveActivityManager.shared.startActivity(
- attributes: attributes,
- contentState: state
-)
-
-// Update
-await LiveActivityManager.shared.updateActivity(
- activity,
- with: DeliveryAttributes.ContentState(
- status: .arriving,
- estimatedArrival: Date().addingTimeInterval(300),
- driverName: "John",
- currentStep: 3
- )
-)
-
-// End
-await LiveActivityManager.shared.endActivity(activity)
-```
+**1. Add the package**
-### Dynamic Island Views
+Your app needs a widget extension. If it has none yet, choose **File › New › Target…** in
+Xcode and pick **Widget Extension**. Then choose **File › Add Package Dependencies…**, paste
+this URL into the search field at the top right and choose **Add Package**:
-```swift
-struct DeliveryActivityConfiguration: Widget {
- var body: some WidgetConfiguration {
- ActivityConfiguration(for: DeliveryAttributes.self) { context in
- // Lock screen view
- DeliveryActivityView(context: context)
- } dynamicIsland: { context in
- DynamicIsland {
- // Expanded view
- DynamicIslandExpandedRegion(.leading) {
- Image(systemName: context.state.status.icon)
- }
- DynamicIslandExpandedRegion(.trailing) {
- Text(context.state.estimatedArrival, style: .timer)
- }
- DynamicIslandExpandedRegion(.bottom) {
- ProgressView(value: Double(context.state.currentStep), total: 4)
- }
- } compactLeading: {
- Image(systemName: context.state.status.icon)
- } compactTrailing: {
- Text(context.state.estimatedArrival, style: .timer)
- } minimal: {
- Image(systemName: context.state.status.icon)
- }
- }
- }
-}
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
```
----
+In the next dialog, set **Add to Target** for `WidgetDevelopmentKit` to your widget
+extension and choose **Add Package**.
-## 🖱️ Interactive Widgets
+**2. Import the module**
-**iOS 17+ Only** — Add buttons, toggles, and interactive elements.
+At the top of a Swift file in the widget extension:
-### Available Interactive Templates
+```swift
+import WidgetDevelopmentKit
+```
-- `InteractiveToggleWidget` — Toggle switches
-- `InteractiveCounterWidget` — Increment/decrement counters
-- `InteractiveTaskListWidget` — Task completion toggles
-- `InteractiveQuickActionsWidget` — Action buttons grid
-- `InteractiveTimerWidget` — Timer controls
-- `InteractiveHabitWidget` — Habit checkmarks
-- `InteractiveRatingWidget` — Star ratings
-- `InteractiveWaterWidget` — Water intake buttons
+**3. Use it**
-### Example
+Add this widget to the extension. It counts down to a date with the package's
+`CountdownWidget` view. Then list `LaunchCountdownWidget()` in the extension's
+`WidgetBundle`, the type marked `@main`.
```swift
-import AppIntents
-import iOSWidgetKit
-
-// Interactive counter widget
-struct MyInteractiveWidget: View {
- let counterId = "daily_counter"
- @AppStorage("counter_daily_counter", store: UserDefaults(suiteName: "group.widget"))
- var count = 0
-
- var body: some View {
- InteractiveCounterWidget(
- title: "Daily Count",
- counterId: counterId,
- currentValue: count,
- accentColor: .blue
- )
- }
+struct LaunchEntry: TimelineEntry {
+ let date: Date
}
-// Task list with toggles
-struct TaskWidget: View {
- var body: some View {
- InteractiveTaskListWidget(
- tasks: [
- .init(id: "1", title: "Morning workout", isCompleted: true, priority: .high),
- .init(id: "2", title: "Read 30 minutes", isCompleted: false, priority: .medium),
- .init(id: "3", title: "Call mom", isCompleted: false, priority: .low)
- ],
- listTitle: "Today's Tasks"
- )
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
}
-}
-```
-
----
-
-## 📺 StandBy Mode
-
-**iOS 17+ Only** — Full-screen widgets for StandBy mode on iPhone.
-
-### StandBy Templates
-
-| Template | Description |
-|----------|-------------|
-| `StandByClockWidget` | Digital/Analog clocks |
-| `StandByPhotoWidget` | Photo frames |
-| `StandByWeatherWidget` | Weather display |
-| `StandByCalendarWidget` | Calendar view |
-| `StandByFitnessWidget` | Activity rings |
-| `StandByMusicWidget` | Now playing |
-| `StandByCountdownWidget` | Event countdown |
-### Example
-
-```swift
-import iOSWidgetKit
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
-struct MyStandByWidget: View {
- var body: some View {
- StandByClockWidget(
- date: Date(),
- style: .flipClock,
- showDate: true,
- accentColor: .white
- )
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
}
}
-// Apply StandBy optimizations
-struct OptimizedWidget: View {
- var body: some View {
- VStack {
- Text("Hello")
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
}
- .standByOptimized(nightModeColor: .red)
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
}
}
```
----
+Run the app on an iPhone simulator. On the Home Screen, touch and hold an empty area, tap
+**Edit › Add Widget**, find your app and add **Countdown**. The same code is in
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
-## 🔒 Lock Screen Widgets
+## Installation
-### 15 Lock Screen Templates
-
-**Circular Widgets:**
-- `CircularProgressWidget` — Progress gauge
-- `CircularIconWidget` — Simple icon
-- `CircularRingWidget` — Activity rings
-
-**Rectangular Widgets:**
-- `RectangularTextWidget` — Multi-line text
-- `RectangularStatsWidget` — Statistics
-- `RectangularProgressWidget` — Progress bar
-- `RectangularCalendarWidget` — Events
-- `RectangularWeatherWidget` — Weather
+### Swift Package Manager
-**Inline Widgets:**
-- `InlineTextWidget` — Text with icon
-- `InlineStatsWidget` — Quick stats
+In Xcode, choose **File › Add Package Dependencies…** and enter the repository URL:
-**Multi-Family Widgets:**
-- `LockScreenBatteryWidget` — Battery (all sizes)
-- `LockScreenTimerWidget` — Timer (all sizes)
-- `LockScreenFitnessWidget` — Fitness (all sizes)
-- `LockScreenCountdownWidget` — Countdown (all sizes)
-- `LockScreenQuickActionWidget` — Actions (all sizes)
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
-### Example
+Or add it to the `dependencies` in your `Package.swift`:
```swift
-struct MyLockScreenWidget: Widget {
- var body: some WidgetConfiguration {
- StaticConfiguration(kind: "LockScreen", provider: Provider()) { entry in
- // Automatically adapt to family
- switch entry.family {
- case .accessoryCircular:
- CircularProgressWidget(
- progress: 0.7,
- icon: "star.fill",
- accentColor: .blue
- )
- case .accessoryRectangular:
- RectangularStatsWidget(
- stats: [("Steps", "8,234"), ("Cal", "450"), ("Dist", "4.2mi")],
- title: "Today"
- )
- case .accessoryInline:
- InlineTextWidget(icon: "flame.fill", text: "450 calories burned")
- default:
- EmptyView()
- }
- }
- .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline])
- }
-}
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
```
----
+Releases start at 2.0.0; the earlier `v1.0.0` tag predates the current code and does not
+build. The package has no third-party dependencies.
-## 📊 Charts in Widgets
+## Usage
-SwiftUI Charts integration for beautiful data visualization.
+Every Swift example in this section is taken from
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), which CI builds, or from
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift),
+which is compiled with the tests. A test fails if a block here no longer matches that code.
-### Available Chart Types
+### Read shared data in a timeline provider
-| Chart | Description |
-|-------|-------------|
-| `WidgetBarChart` | Vertical bar chart |
-| `WidgetLineChart` | Line chart with area |
-| `WidgetSparkline` | Minimal sparkline |
-| `WidgetPieChart` | Pie/donut chart |
-| `WidgetProgressRing` | Circular progress |
-| `WidgetMultiLineChart` | Multiple series |
-| `WidgetHorizontalBarChart` | Horizontal bars |
-| `WidgetActivityChart` | GitHub-style activity |
-| `WidgetStatsChart` | Stats with sparkline |
-
-### Example
+`TimelineSchedule` produces the entry dates, `TimelineBuilder` sorts the entries and turns a
+`WidgetUpdatePolicy` into WidgetKit's reload policy, and `WidgetSnapshotStore` reads what the
+app saved to the shared App Group.
```swift
-import iOSWidgetKit
-import Charts
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
-struct ChartWidget: View {
- var body: some View {
- VStack {
- // Sparkline
- WidgetSparkline(
- values: [10, 25, 15, 30, 22, 35, 28],
- color: .blue,
- showGradient: true
- )
- .frame(height: 50)
-
- // Stats with chart
- WidgetStatsChart(
- title: "Revenue",
- value: "$12,450",
- change: 12.5,
- sparklineData: [100, 120, 110, 145, 160, 155, 180],
- accentColor: .green
- )
-
- // Horizontal bar comparison
- WidgetHorizontalBarChart(
- data: [
- .init(label: "Mon", value: 45),
- .init(label: "Tue", value: 62),
- .init(label: "Wed", value: 38)
- ],
- accentColor: .purple
- )
- }
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
}
-}
-```
-
----
-
-## ⏱️ Timeline Management
-Advanced timeline management for optimal battery and freshness.
-
-### Features
-
-- **Smart Refresh Strategies** — Time-based, battery-aware, content-aware
-- **Caching** — Built-in cache layer
-- **Timeline Builder** — Fluent API
-- **Metrics** — Performance tracking
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
-### Example
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
-```swift
-import iOSWidgetKit
-
-// Use Timeline Builder
-let timeline = TimelineBuilder()
- .addEntry(MyEntry(date: Date(), data: currentData))
- .addEntry(MyEntry(date: Date().addingTimeInterval(3600), data: currentData))
- .reloadAfter(1800) // 30 minutes
- .build()
-
-// Battery-aware refresh
-let strategy = BatteryAwareRefreshStrategy(
- normalInterval: 900, // 15 min normally
- lowBatteryInterval: 3600, // 1 hour on low battery
- lowBatteryThreshold: 0.2
-)
-
-// Use cache
-TimelineCacheManager.shared.store(myData, forKey: "widget_data", expiration: 300)
-if let cached: MyData = TimelineCacheManager.shared.retrieve(MyData.self, forKey: "widget_data") {
- // Use cached data
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
}
```
----
-
-## 🌐 Network Data Support
+### Save data in the app
-Fetch and display remote data in widgets.
+The app writes the value with a lifetime and asks WidgetKit to reload the widget:
```swift
-import iOSWidgetKit
-
-// Simple fetch
-let data = try await NetworkDataProvider.shared.fetch(
- WeatherResponse.self,
- from: URL(string: "https://api.weather.com/data")!
-)
-
-// With caching
-let provider = CachedNetworkProvider(
- cacheKey: "weather",
- cacheDuration: 600
-)
-let weather = try await provider.fetch(from: url)
-
-// Background refresh
-BackgroundRefreshCoordinator.shared.scheduleBackgroundRefresh(
- identifier: "weather_widget",
- afterInterval: 1800
-)
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
```
----
+Add the **App Groups** capability to the app and the extension with the same identifier.
+The store uses `UserDefaults`, which is not encrypted, so keep secrets out of it.
-## 🔗 Deep Linking
-
-Connect widget taps to specific app content.
+### Show an entry
```swift
-import iOSWidgetKit
-
-// Build deep link URL
-let url = WidgetDeepLinkManager.shared.buildContentURL(
- contentType: "task",
- contentId: "123",
- parameters: ["source": "widget"]
-)
-
-// In widget view
-Link(destination: url!) {
- TaskRow(task: task)
-}
+struct StepsWidgetView: View {
+ let entry: StepsEntry
-// Handle in app
-@main
-struct MyApp: App {
- var body: some Scene {
- WindowGroup {
- ContentView()
- .onWidgetURL { url in
- let params = WidgetDeepLinkManager.shared.parseParameters(from: url)
- // Navigate to content
- }
- }
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
}
}
```
----
-
-## 📦 Installation
+Views that show time-dependent values (`CountdownWidget`, `StandByCountdownWidget`,
+`LockScreenCountdownWidget`) take a `referenceDate`; pass `entry.date` so each entry renders
+its own moment.
-### Swift Package Manager
+### Add a button to a widget
```swift
-dependencies: [
- .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
-]
-```
-
-### CocoaPods
-
-```ruby
-pod 'WidgetDevelopmentKit', '~> 2.0'
-```
-
----
-
-## 🚀 Quick Start
-
-### 1. Add Widget Extension
-
-File → New → Target → Widget Extension
-
-### 2. Import the Kit
-
-```swift
-import WidgetKit
-import SwiftUI
-import iOSWidgetKit
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
```
-### 3. Create Your Widget
+The intents run in the widget extension and write to `WidgetStateStore.shared`, which uses
+the App Group named by the `WidgetDevelopmentKitAppGroup` key in Info.plist. Add the key to
+both the app and the extension, and register the package's intents:
```swift
-struct MyWidget: Widget {
- let kind: String = "MyWidget"
-
- var body: some WidgetConfiguration {
- StaticConfiguration(kind: kind, provider: MyProvider()) { entry in
- WeatherWidget(
- temperature: entry.temperature,
- condition: entry.condition,
- location: entry.location,
- high: entry.high,
- low: entry.low
- )
- }
- .configurationDisplayName("Weather")
- .description("Shows current weather.")
- .supportedFamilies([.systemSmall, .systemMedium])
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
}
}
```
----
+### Load data from a server
-## 📁 Project Structure
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
```
-iOS-Widget-Development-Kit/
-├── Sources/
-│ ├── Templates/ # 20+ Home Screen widget templates
-│ ├── LiveActivities/ # 10+ Live Activity templates
-│ ├── Interactive/ # iOS 17 interactive widgets
-│ ├── StandBy/ # StandBy mode widgets
-│ ├── LockScreen/ # 15 Lock Screen widgets
-│ ├── Charts/ # SwiftUI Charts for widgets
-│ ├── Core/ # Timeline management
-│ ├── Network/ # Network data support
-│ └── Configuration/ # Deep linking & config
-├── Examples/ # Sample implementations
-├── Tests/ # Comprehensive tests
-└── Documentation/ # Guides & tutorials
-```
-
----
-## 📋 Requirements
-
-| Requirement | Minimum |
-|-------------|---------|
-| iOS | 16.0+ |
-| Xcode | 15.0+ |
-| Swift | 5.9+ |
-
-**Feature Requirements:**
-| Feature | iOS Version |
-|---------|-------------|
-| Home Screen Widgets | 14.0+ |
-| Lock Screen Widgets | 16.0+ |
-| Live Activities | 16.1+ |
-| Dynamic Island | 16.1+ |
-| Interactive Widgets | 17.0+ |
-| StandBy Mode | 17.0+ |
-
----
-
-## 📖 Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [Widget Design Guide](Documentation/WidgetDesign.md) | Design best practices |
-| [Timeline Management](Documentation/TimelineManagement.md) | Refresh strategies |
-| [Live Activities Guide](Documentation/LiveActivities.md) | Dynamic Island setup |
-| [Interactive Widgets](Documentation/InteractiveWidgets.md) | iOS 17 interactions |
-| [StandBy Mode](Documentation/StandByMode.md) | Full-screen widgets |
-| [Network Data](Documentation/NetworkData.md) | Remote data fetching |
-| [Best Practices](Documentation/BestPractices.md) | Performance tips |
-
----
-
-## 🤝 Contributing
-
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
-
-```bash
-git checkout -b feature/amazing-widget
-git commit -m "feat(widgets): add amazing widget template"
-git push origin feature/amazing-widget
+`WidgetDataLoader` uses an ephemeral session with short timeouts that does not wait for
+connectivity. It retries 5xx and 408 responses, timeouts and offline errors (once by
+default; set a `RetryPolicy` to change it), but not 4xx responses or decoding errors.
+
+## Demo
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The images are rendered from the package's views with `ImageRenderer` by
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh). They are drawn outside
+WidgetKit, so the widget frame, Lock Screen vibrancy and StandBy night mode are approximated
+rather than produced by the system.
+
+To try the widgets yourself, open
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) and run
+the **WidgetKitExample** scheme on an iPhone simulator; [`Examples/README.md`](Examples/README.md)
+explains the three widgets and how to add them to the Home Screen.
+
+## Documentation
+
+Reference documentation and articles:
+
+- [API reference](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ on GitHub Pages, built from the DocC comments in the source.
+- In Xcode: **Product › Build Documentation**, or
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Guides
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ add a widget extension and the package, share data through an App Group, build the
+ timeline and render an entry.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ configure the App Group, register the intents, add buttons and read their state in the
+ provider and the app.
+
+## Requirements
+
+| Platform | Minimum version |
+| --------- | --------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Toolchain | Swift 6.0 |
+
+Lock Screen views and Live Activities are iOS only. The macOS target exists so the
+platform-independent code and its tests run with `swift test`. CI builds with the default
+Xcode of GitHub's `macos-26` image; local development uses Xcode 27. Older Xcode versions have
+not been tried.
+
+## Architecture
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
```
----
-
-## 📄 License
+Views stay thin: arithmetic that can go wrong with real data (zero goals, `NaN`, reversed
+date ranges, daylight-saving days) lives in `Core` and `Timeline` as pure functions with unit
+tests. Types that touch storage or the network take their dependencies (`UserDefaults`,
+clock, transport, sleep) as parameters, so they can be tested without an App Group or a
+server. SwiftUI view bodies are not snapshot-tested.
-MIT License — see [LICENSE](LICENSE) for details.
+Run the tests on macOS and on an iOS simulator:
----
-
-
-
-## 👨💻 Author
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
-**Muhittin Camdali**
+Three iOS tests are skipped on purpose: they render the README images and run only through
+`scripts/render-screenshots.sh`.
-[](https://github.com/muhittincamdali)
-[](https://linkedin.com/in/muhittincamdali)
+## Roadmap
----
+- Tag a release that matches the current code, so the package can be added by version.
+- Snapshot tests for the view bodies.
+- An example Live Activity in the example app.
-**⭐ Star this repo if you find it useful!**
+The [CHANGELOG](CHANGELOG.md) records what changed so far, including how the package was
+restored in October 2026 after the `v1.0.0` code turned out not to build.
----
+## Contributing
-## 📈 Star History
+Contributions are welcome. Read the [contributing guide](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) and the [code of conduct](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) before opening a pull request. Report security issues privately as described in the [security policy](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md).
-
-
-
-
-
-
-
+## License
-
+Released under the MIT license. See [LICENSE](LICENSE).
diff --git a/README.pt-BR.md b/README.pt-BR.md
new file mode 100644
index 0000000..07704e1
--- /dev/null
+++ b/README.pt-BR.md
@@ -0,0 +1,373 @@
+
+
+
+
+
+> Esta é uma tradução do README em inglês. Se houver diferença, vale a versão em inglês.
+
+
+
+WidgetDevelopmentKit é um pacote Swift para quem cria widgets para apps iOS. Ele traz views
+SwiftUI prontas para widgets da Tela de Início, da Tela Bloqueada e do StandBy, views de
+gráficos no tamanho de um widget, utilitários para timelines e para os dados que o app
+compartilha com o widget, App Intents para os botões dos widgets, além de atributos e views do
+ActivityKit para Live Activities. Você continua escrevendo a extensão de widget; o pacote
+poupa o trabalho das views e da lógica de datas, armazenamento e novas tentativas de que todo
+widget precisa.
+
+## Destaques
+
+- **20 modelos para a Tela de Início** — clima, estatísticas, finanças, calendário, contagem
+ regressiva, relógio, notas, citação, música, podcast, notícias, anéis de atividade,
+ acompanhamento de hábitos, tarefas, água, bateria e mais.
+- **Tela Bloqueada e StandBy** — 15 views de acessório (circular, retangular, em linha) e 7
+ views de StandBy.
+- **Utilitários de timeline** — datas das entradas, políticas de recarga e um armazenamento de
+ snapshots com validade, para que o widget leia o que o app salvou por meio de um App Group.
+- **Widgets interativos** — 5 App Intents e 8 views com botões que os executam.
+- **Live Activities** — 10 tipos de `ActivityAttributes` com views para a Tela Bloqueada e a
+ Dynamic Island compacta, e uma máquina de estados que rejeita atualizações fora de ordem.
+- **Lógica testada** — o código de datas, números e novas tentativas é coberto por testes do
+ Swift Testing, incluindo casos extremos como `NaN`, metas iguais a zero e dias de mudança de
+ horário de verão.
+
+## Início rápido
+
+**1. Adicione o pacote**
+
+Seu app precisa de uma extensão de widget. Se ainda não tiver uma, escolha **File › New ›
+Target…** no Xcode e selecione **Widget Extension**. Depois escolha **File › Add Package
+Dependencies…**, cole esta URL no campo de busca no canto superior direito e clique em **Add
+Package**:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Na janela seguinte, defina **Add to Target** de `WidgetDevelopmentKit` como sua extensão de
+widget e clique em **Add Package**.
+
+**2. Importe o módulo**
+
+No início de um arquivo Swift da extensão de widget:
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. Use**
+
+Adicione este widget à extensão. Ele faz uma contagem regressiva até uma data com a view
+`CountdownWidget` do pacote. Em seguida, inclua `LaunchCountdownWidget()` no `WidgetBundle` da
+extensão, o tipo marcado com `@main`.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Execute o app em um simulador de iPhone. Na Tela de Início, toque e segure uma área vazia,
+toque em **Edit › Add Widget**, encontre seu app e adicione **Countdown**. O mesmo código está
+em [`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
+
+## Instalação
+
+### Swift Package Manager
+
+No Xcode, escolha **File › Add Package Dependencies…** e informe a URL do repositório:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Ou adicione-o às `dependencies` do seu `Package.swift`:
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+As versões começam em 2.0.0; a tag anterior, `v1.0.0`, é anterior ao código atual e não
+compila. O pacote não tem dependências de terceiros.
+
+## Uso
+
+Todos os exemplos em Swift desta seção vêm de
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), que a CI compila, ou de
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift), que é
+compilado com os testes. Um teste falha se um bloco daqui deixar de corresponder a esse código.
+
+### Ler dados compartilhados em um provedor de timeline
+
+`TimelineSchedule` gera as datas das entradas, `TimelineBuilder` ordena as entradas e converte
+uma `WidgetUpdatePolicy` na política de recarga do WidgetKit, e `WidgetSnapshotStore` lê o que
+o app salvou no App Group compartilhado.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Salvar dados no app
+
+O app grava o valor com um prazo de validade e pede ao WidgetKit que recarregue o widget:
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Adicione a capability **App Groups** ao app e à extensão com o mesmo identificador. O
+armazenamento usa `UserDefaults`, que não é criptografado; não guarde segredos nele.
+
+### Mostrar uma entrada
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Views que mostram valores que dependem do tempo (`CountdownWidget`, `StandByCountdownWidget`,
+`LockScreenCountdownWidget`) recebem um `referenceDate`; passe `entry.date` para que cada
+entrada mostre o próprio momento.
+
+### Adicionar um botão a um widget
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Os intents rodam na extensão de widget e gravam em `WidgetStateStore.shared`, que usa o App
+Group indicado na chave `WidgetDevelopmentKitAppGroup` do Info.plist. Adicione a chave ao app e
+à extensão e registre os intents do pacote:
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Carregar dados de um servidor
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader` usa uma sessão efêmera com tempos limite curtos, que não espera haver
+conexão. Ele tenta de novo respostas 5xx e 408, tempos limite esgotados e erros de falta de
+conexão (uma vez por padrão; defina uma `RetryPolicy` para mudar isso), mas não respostas 4xx
+nem erros de decodificação.
+
+## Demonstração
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+As imagens são desenhadas a partir das views do pacote com `ImageRenderer` por
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh). Como são desenhadas fora do
+WidgetKit, a moldura do widget, a vibrância da Tela Bloqueada e o modo noturno do StandBy são
+aproximações, e não produzidos pelo sistema.
+
+Para testar os widgets, abra
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) e execute
+o esquema **WidgetKitExample** em um simulador de iPhone;
+[`Examples/README.md`](Examples/README.md) explica os três widgets e como adicioná-los à Tela
+de Início.
+
+## Documentação
+
+Referência da API e artigos:
+
+- [Referência da API](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ no GitHub Pages, gerada a partir dos comentários DocC do código-fonte.
+- No Xcode: **Product › Build Documentation**, ou
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Guias
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ adicionar uma extensão de widget e o pacote, compartilhar dados por um App Group, montar a
+ timeline e desenhar uma entrada.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ configurar o App Group, registrar os intents, adicionar botões e ler o estado deles no
+ provedor e no app.
+
+## Requisitos
+
+| Plataforma | Versão mínima |
+| ----------- | ------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Ferramentas | Swift 6.0 |
+
+As views da Tela Bloqueada e as Live Activities existem apenas no iOS. O alvo macOS existe
+para que o código independente de plataforma e seus testes rodem com `swift test`. A CI compila
+com o Xcode padrão da imagem `macos-26` do GitHub; o desenvolvimento local usa o Xcode 27.
+Versões mais antigas do Xcode não foram testadas.
+
+## Arquitetura
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+As views são enxutas: cálculos que podem dar errado com dados reais (metas iguais a zero,
+`NaN`, intervalos de datas invertidos, dias de mudança de horário de verão) ficam em `Core` e
+`Timeline` como funções puras com testes unitários. Tipos que acessam armazenamento ou rede
+recebem suas dependências (`UserDefaults`, relógio, transporte, espera) como parâmetros, então
+podem ser testados sem um App Group ou um servidor. Os corpos das views SwiftUI não têm testes
+de snapshot.
+
+Execute os testes no macOS e em um simulador iOS:
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Três testes de iOS são pulados de propósito: eles desenham as imagens do README e só rodam por
+meio de `scripts/render-screenshots.sh`.
+
+## Roteiro
+
+- Criar a tag de uma versão que corresponda ao código atual, para que o pacote possa ser
+ adicionado por versão.
+- Testes de snapshot para os corpos das views.
+- Uma Live Activity de exemplo no app de exemplo.
+
+O [CHANGELOG](CHANGELOG.md) registra o que mudou até agora, incluindo como o pacote foi
+restaurado em outubro de 2026, depois que se descobriu que o código da `v1.0.0` não compilava.
+
+## Como contribuir
+
+Contribuições são bem-vindas. Leia o [guia de contribuição](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) e o [código de conduta](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) antes de abrir um pull request. Relate problemas de segurança de forma privada, como descrito na [política de segurança](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md).
+
+## Licença
+
+Publicado sob a licença MIT. Veja [LICENSE](LICENSE).
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 0000000..113706d
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,376 @@
+
+
+
+
+
+> Это перевод README на английском языке. Если они расходятся, актуальна английская версия.
+
+
+
+WidgetDevelopmentKit — это Swift-пакет для разработчиков, которые создают виджеты для своих
+iOS-приложений. В нём есть готовые SwiftUI-представления для виджетов экрана «Домой», экрана
+блокировки и StandBy, представления графиков под размер виджета, вспомогательные типы для
+таймлайнов и для данных, которые приложение передаёт виджету, App Intents для кнопок в
+виджетах, а также атрибуты и представления ActivityKit для Live Activities. Расширение с
+виджетами вы по-прежнему пишете сами; пакет избавляет от работы над представлениями и над
+логикой дат, хранения и повторных попыток, которая нужна любому виджету.
+
+## Основные возможности
+
+- **20 шаблонов для экрана «Домой»** — погода, статистика, финансы, календарь, обратный
+ отсчёт, часы, заметки, цитата, музыка, подкаст, новости, кольца активности, трекер
+ привычек, список дел, вода, батарея и другие.
+- **Экран блокировки и StandBy** — 15 представлений для аксессуарных семейств (круглые,
+ прямоугольные, строчные) и 7 представлений для StandBy.
+- **Помощники для таймлайнов** — даты записей, политики перезагрузки и хранилище снимков со
+ сроком действия, чтобы виджет читал то, что приложение сохранило через App Group.
+- **Интерактивные виджеты** — 5 App Intents и 8 представлений с кнопками, которые их
+ запускают.
+- **Live Activities** — 10 типов `ActivityAttributes` с представлениями для экрана блокировки
+ и компактного Dynamic Island, а также конечный автомат, который отклоняет обновления,
+ пришедшие не по порядку.
+- **Протестированная логика** — код для дат, чисел и повторных попыток покрыт тестами Swift
+ Testing, включая граничные случаи вроде `NaN`, нулевой цели и дней перехода на летнее время.
+
+## Быстрый старт
+
+**1. Добавьте пакет**
+
+Приложению нужно расширение с виджетами. Если его ещё нет, выберите в Xcode **File › New ›
+Target…** и затем **Widget Extension**. После этого выберите **File › Add Package
+Dependencies…**, вставьте этот адрес в поле поиска в правом верхнем углу и нажмите **Add
+Package**:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+В следующем окне в столбце **Add to Target** для `WidgetDevelopmentKit` выберите расширение
+с виджетами и нажмите **Add Package**.
+
+**2. Импортируйте модуль**
+
+В начале Swift-файла в расширении с виджетами:
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. Используйте**
+
+Добавьте этот виджет в расширение. Он показывает обратный отсчёт до даты с помощью
+представления `CountdownWidget` из пакета. Затем добавьте `LaunchCountdownWidget()` в
+`WidgetBundle` расширения — тип, помеченный `@main`.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Запустите приложение в симуляторе iPhone. На экране «Домой» нажмите и удерживайте пустое
+место, коснитесь **Edit › Add Widget**, найдите своё приложение и добавьте **Countdown**. Тот
+же код есть в
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift).
+
+## Установка
+
+### Swift Package Manager
+
+В Xcode выберите **File › Add Package Dependencies…** и введите адрес репозитория:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Или добавьте его в `dependencies` вашего `Package.swift`:
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+Релизы начинаются с 2.0.0; более ранний тег `v1.0.0` старше текущего кода и не
+собирается. У пакета нет сторонних зависимостей.
+
+## Использование
+
+Все примеры на Swift в этом разделе взяты из
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample), который собирает CI, или из
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift),
+который компилируется вместе с тестами. Если блок кода здесь перестанет совпадать с этим кодом,
+тест упадёт.
+
+### Чтение общих данных в провайдере таймлайна
+
+`TimelineSchedule` создаёт даты записей, `TimelineBuilder` сортирует записи и превращает
+`WidgetUpdatePolicy` в политику перезагрузки WidgetKit, а `WidgetSnapshotStore` читает то, что
+приложение сохранило в общую App Group.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Сохранение данных в приложении
+
+Приложение записывает значение со сроком действия и просит WidgetKit перезагрузить виджет:
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Добавьте приложению и расширению возможность **App Groups** с одним и тем же идентификатором.
+Хранилище использует `UserDefaults`, которое не шифруется, поэтому не храните в нём секреты.
+
+### Отображение записи
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Представления, показывающие значения, которые зависят от времени (`CountdownWidget`,
+`StandByCountdownWidget`, `LockScreenCountdownWidget`), принимают `referenceDate`; передавайте
+`entry.date`, чтобы каждая запись показывала свой момент времени.
+
+### Кнопка в виджете
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Интенты выполняются в расширении с виджетами и записывают данные в `WidgetStateStore.shared`.
+Это хранилище использует App Group, указанную в ключе `WidgetDevelopmentKitAppGroup` в
+Info.plist. Добавьте ключ и в приложение, и в расширение и зарегистрируйте интенты пакета:
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Загрузка данных с сервера
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader` использует эфемерную сессию с короткими тайм-аутами, которая не ждёт
+появления сети. Он повторяет запросы при ответах 5xx и 408, тайм-аутах и ошибках отсутствия
+сети (по умолчанию один раз; изменить можно через `RetryPolicy`), но не при ответах 4xx и
+ошибках декодирования.
+
+## Демо
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Изображения отрисованы из представлений пакета с помощью `ImageRenderer` скриптом
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh). Поскольку они рисуются вне
+WidgetKit, рамка виджета, эффект vibrancy на экране блокировки и ночной режим StandBy лишь
+приблизительно повторяют то, что показывает система.
+
+Чтобы попробовать виджеты самостоятельно, откройте
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) и запустите
+схему **WidgetKitExample** в симуляторе iPhone; в
+[`Examples/README.md`](Examples/README.md) описаны три виджета и то, как добавить их на экран
+«Домой».
+
+## Документация
+
+Справочник API и статьи:
+
+- [Справочник API](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/)
+ на GitHub Pages, созданный из DocC-комментариев в исходном коде.
+- В Xcode: **Product › Build Documentation** или
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Руководства
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ добавление расширения с виджетами и пакета, обмен данными через App Group, построение
+ таймлайна и отрисовка записи.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ настройка App Group, регистрация интентов, добавление кнопок и чтение их состояния в
+ провайдере и в приложении.
+
+## Требования
+
+| Платформа | Минимальная версия |
+| ----------- | ------------------ |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Инструменты | Swift 6.0 |
+
+Представления для экрана блокировки и Live Activities есть только в iOS. Цель для macOS нужна,
+чтобы платформенно-независимый код и его тесты запускались через `swift test`. CI собирает пакет
+с Xcode, установленным по умолчанию в образе `macos-26` на GitHub; для локальной разработки используется
+Xcode 27. Более старые версии Xcode не проверялись.
+
+## Архитектура
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+Представления остаются тонкими: вычисления, которые могут сломаться на реальных данных
+(нулевые цели, `NaN`, перевёрнутые диапазоны дат, дни перехода на летнее время), вынесены в
+`Core` и `Timeline` как чистые функции с модульными тестами. Типы, которые работают с
+хранилищем или сетью, получают зависимости (`UserDefaults`, часы, транспорт, ожидание) через
+параметры, поэтому их можно тестировать без App Group и сервера. Для body SwiftUI-представлений
+снапшот-тестов нет.
+
+Запустите тесты на macOS и в симуляторе iOS:
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Три iOS-теста пропускаются намеренно: они отрисовывают изображения для README и запускаются
+только через `scripts/render-screenshots.sh`.
+
+## План развития
+
+- Отметить тегом релиз, соответствующий текущему коду, чтобы пакет можно было подключать по
+ версии.
+- Снапшот-тесты для body представлений.
+- Пример Live Activity в демонстрационном приложении.
+
+В [CHANGELOG](CHANGELOG.md) записаны все изменения на сегодня, в том числе то, как пакет был
+восстановлен в октябре 2026 года, после того как выяснилось, что код `v1.0.0` не собирается.
+
+## Участие в разработке
+
+Мы рады вашему участию. Перед открытием pull request прочитайте [руководство для участников](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) и [кодекс поведения](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md). О проблемах безопасности сообщайте конфиденциально, как описано в [политике безопасности](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md).
+
+## Лицензия
+
+Распространяется по лицензии MIT. Подробнее — в файле [LICENSE](LICENSE).
diff --git a/README.tr.md b/README.tr.md
new file mode 100644
index 0000000..39ec0fb
--- /dev/null
+++ b/README.tr.md
@@ -0,0 +1,376 @@
+
+
+
+
+
+> Bu belge İngilizce README'nin çevirisidir. İkisi arasında fark varsa güncel olan İngilizce sürümdür.
+
+
+
+WidgetDevelopmentKit, iOS uygulamalarına widget geliştirenler için bir Swift paketidir. Ana
+Ekran, Kilitli Ekran ve StandBy widget'ları için hazır SwiftUI görünümleri, widget boyutuna
+uygun grafik görünümleri, zaman çizelgeleri ve uygulamanın widget'la paylaştığı veriler için
+yardımcılar, widget düğmeleri için App Intents ve Live Activities için ActivityKit
+öznitelikleri ile görünümleri içerir. Widget uzantısını yine siz yazarsınız; paket sizi
+görünümlerle ve her widget'ın ihtiyaç duyduğu tarih, depolama ve yeniden deneme mantığıyla
+uğraşmaktan kurtarır.
+
+## Öne çıkanlar
+
+- **20 Ana Ekran şablonu** — hava durumu, istatistik, finans, takvim, geri sayım, saat, not,
+ alıntı, müzik, podcast, haber, fitness halkaları, alışkanlık takibi, yapılacaklar, su, pil
+ ve daha fazlası.
+- **Kilitli Ekran ve StandBy** — 15 aksesuar görünümü (dairesel, dikdörtgen, satır içi) ve 7
+ StandBy görünümü.
+- **Zaman çizelgesi yardımcıları** — giriş tarihleri, yeniden yükleme politikaları ve süresi
+ dolan değerleri bilen bir anlık görüntü deposu; widget, uygulamanın App Group üzerinden
+ kaydettiği veriyi okur.
+- **Etkileşimli widget'lar** — 5 App Intent ve bunları çalıştıran düğmelere sahip 8 görünüm.
+- **Live Activities** — Kilitli Ekran ve kompakt Dynamic Island görünümleriyle 10
+ `ActivityAttributes` türü ve sırası karışmış güncellemeleri reddeden bir durum makinesi.
+- **Test edilmiş mantık** — tarih, sayı ve yeniden deneme kodu Swift Testing testleriyle
+ kapsanır; `NaN`, sıfır hedef ve yaz saati geçiş günleri gibi uç durumlar da dahil.
+
+## Hızlı başlangıç
+
+**1. Paketi ekleyin**
+
+Uygulamanızın bir widget uzantısı olmalı. Henüz yoksa Xcode'da **File › New › Target…**
+menüsünü seçin ve **Widget Extension**'ı seçin. Ardından **File › Add Package
+Dependencies…** menüsünü seçin, bu adresi sağ üstteki arama alanına yapıştırın ve **Add
+Package**'a tıklayın:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Sonraki pencerede `WidgetDevelopmentKit` için **Add to Target** sütununu widget uzantınız
+olarak ayarlayın ve **Add Package**'a tıklayın.
+
+**2. Modülü içe aktarın**
+
+Widget uzantısındaki bir Swift dosyasının en üstüne ekleyin:
+
+```swift
+import WidgetDevelopmentKit
+```
+
+**3. Kullanın**
+
+Bu widget'ı uzantıya ekleyin. Paketin `CountdownWidget` görünümüyle bir tarihe geri sayım
+yapar. Ardından `LaunchCountdownWidget()` satırını uzantının `WidgetBundle`'ına, yani
+`@main` ile işaretli türe ekleyin.
+
+```swift
+struct LaunchEntry: TimelineEntry {
+ let date: Date
+}
+
+struct LaunchProvider: TimelineProvider {
+ func placeholder(in context: Context) -> LaunchEntry {
+ LaunchEntry(date: .now)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (LaunchEntry) -> Void) {
+ completion(LaunchEntry(date: .now))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ // One entry per hour for the next six hours, then WidgetKit asks again.
+ let entries = TimelineSchedule.dates(from: .now, every: 60 * 60, count: 6).map(LaunchEntry.init)
+ completion(Timeline(entries: entries, policy: .atEnd))
+ }
+}
+
+struct LaunchCountdownWidget: Widget {
+ let launchDay = DateComponents(calendar: .current, year: 2027, month: 1, day: 1).date ?? .now
+
+ var body: some WidgetConfiguration {
+ StaticConfiguration(kind: "launch", provider: LaunchProvider()) { entry in
+ CountdownWidget(title: "Launch", targetDate: launchDay, referenceDate: entry.date)
+ }
+ .configurationDisplayName("Countdown")
+ .supportedFamilies([.systemSmall])
+ }
+}
+```
+
+Uygulamayı bir iPhone simülatöründe çalıştırın. Ana Ekran'da boş bir alana basılı tutun,
+**Edit › Add Widget**'a dokunun, uygulamanızı bulun ve **Countdown**'ı ekleyin. Aynı kod
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample/Widgets/LaunchCountdownWidget.swift)
+içinde de var.
+
+## Kurulum
+
+### Swift Package Manager
+
+Xcode'da **File › Add Package Dependencies…** menüsünü seçin ve depo adresini girin:
+
+```text
+https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git
+```
+
+Ya da `Package.swift` dosyanızdaki `dependencies` listesine ekleyin:
+
+```swift
+dependencies: [
+ .package(url: "https://github.com/muhittincamdali/iOS-Widget-Development-Kit.git", from: "2.0.0")
+],
+targets: [
+ .target(name: "YourApp", dependencies: [
+ .product(name: "WidgetDevelopmentKit", package: "iOS-Widget-Development-Kit")
+ ])
+]
+```
+
+Sürümler 2.0.0 ile başlar; daha önceki `v1.0.0` etiketi güncel koddan eskidir ve
+derlenmez. Paketin üçüncü taraf bağımlılığı yoktur.
+
+## Kullanım
+
+Bu bölümdeki her Swift örneği, CI'ın derlediği
+[`Examples/WidgetKitExample`](Examples/WidgetKitExample) projesinden ya da testlerle birlikte
+derlenen
+[`ReadmeExamplesTests.swift`](Tests/WidgetDevelopmentKitTests/ReadmeExamplesTests.swift)
+dosyasından alınmıştır. Buradaki bir blok o kodla artık eşleşmezse bir test başarısız olur.
+
+### Zaman çizelgesi sağlayıcısında paylaşılan veriyi okuyun
+
+`TimelineSchedule` giriş tarihlerini üretir, `TimelineBuilder` girişleri sıralar ve bir
+`WidgetUpdatePolicy` değerini WidgetKit'in yeniden yükleme politikasına çevirir,
+`WidgetSnapshotStore` ise uygulamanın paylaşılan App Group'a kaydettiklerini okur.
+
+```swift
+struct StepsProvider: TimelineProvider {
+ let store = WidgetSnapshotStore(defaults: UserDefaults(suiteName: "group.com.example.widgets") ?? .standard)
+
+ func placeholder(in context: Context) -> StepsEntry {
+ StepsEntry(date: .now, steps: 6_000)
+ }
+
+ func getSnapshot(in context: Context, completion: @escaping (StepsEntry) -> Void) {
+ completion(placeholder(in: context))
+ }
+
+ func getTimeline(in context: Context, completion: @escaping (Timeline) -> Void) {
+ completion(makeTimeline(now: .now))
+ }
+
+ func makeTimeline(now: Date) -> Timeline {
+ // Written by the app; stale data is better than an empty widget.
+ let steps = store.staleValue(Int.self, forKey: "steps") ?? 0
+ let entries = TimelineSchedule
+ .dates(from: now, every: 15 * 60, count: 4)
+ .map { StepsEntry(date: $0, steps: steps) }
+ return TimelineBuilder(entries: entries)
+ .reloading(.every(minutes: 60), from: now)
+ .build()
+ }
+}
+```
+
+### Uygulamada veriyi kaydedin
+
+Uygulama değeri bir geçerlilik süresiyle yazar ve WidgetKit'ten widget'ı yeniden yüklemesini
+ister:
+
+```swift
+try store.save(steps, forKey: "steps", lifetime: 30 * 60)
+WidgetCenter.shared.reloadTimelines(ofKind: "steps")
+```
+
+Uygulamaya ve uzantıya aynı tanımlayıcıyla **App Groups** yeteneğini ekleyin. Depo
+şifrelenmeyen `UserDefaults` kullanır; gizli bilgileri burada tutmayın.
+
+### Bir girişi gösterin
+
+```swift
+struct StepsWidgetView: View {
+ let entry: StepsEntry
+
+ var body: some View {
+ WidgetProgressRing(progress: Double(entry.steps), total: 10_000, colors: [.green, .mint])
+ .padding()
+ .containerBackground(.fill.tertiary, for: .widget)
+ .widgetURL(WidgetDeepLink(scheme: "steps", host: "today"))
+ }
+}
+```
+
+Zamana bağlı değer gösteren görünümler (`CountdownWidget`, `StandByCountdownWidget`,
+`LockScreenCountdownWidget`) bir `referenceDate` alır; her giriş kendi anını göstersin diye
+`entry.date` değerini verin.
+
+### Widget'a düğme ekleyin
+
+```swift
+struct WaterButton: View {
+ var body: some View {
+ Button(intent: IncrementIntent(counterId: "water", amount: 250)) {
+ Label("+250 ml", systemImage: "drop.fill")
+ }
+ }
+}
+```
+
+Intent'ler widget uzantısında çalışır ve `WidgetStateStore.shared`'a yazar. Bu depo,
+Info.plist'teki `WidgetDevelopmentKitAppGroup` anahtarında adı verilen App Group'u kullanır.
+Anahtarı hem uygulamaya hem uzantıya ekleyin ve paketin intent'lerini kaydedin:
+
+```swift
+struct AppIntentsRoot: AppIntentsPackage {
+ static var includedPackages: [any AppIntentsPackage.Type] {
+ [WidgetDevelopmentKitIntents.self]
+ }
+}
+```
+
+### Sunucudan veri yükleyin
+
+```swift
+struct RandomQuote: Decodable {
+ let text: String
+}
+
+func loadQuote() async throws -> RandomQuote {
+ guard let base = URL(string: "https://api.example.com") else { throw URLError(.badURL) }
+ let endpoint = Endpoint(base: base)
+ .appendingPath("v1/quotes/random")
+ .adding(query: "lang", "en")
+ guard let request = endpoint.request else { throw URLError(.badURL) }
+ return try await WidgetDataLoader().load(RandomQuote.self, from: request)
+}
+```
+
+`WidgetDataLoader`, bağlantıyı beklemeyen ve kısa zaman aşımları olan geçici (ephemeral) bir
+oturum kullanır. 5xx ve 408 yanıtlarını, zaman aşımlarını ve çevrimdışı hatalarını yeniden
+dener (varsayılan olarak bir kez; değiştirmek için bir `RetryPolicy` verin), ancak 4xx
+yanıtlarını ve çözümleme (decoding) hatalarını denemez.
+
+## Demo
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Görseller paketin görünümlerinden
+[`scripts/render-screenshots.sh`](scripts/render-screenshots.sh) ile `ImageRenderer`
+kullanılarak çizilir. WidgetKit dışında çizildikleri için widget çerçevesi, Kilitli Ekran
+canlılığı (vibrancy) ve StandBy gece modu sistem tarafından üretilmez, yaklaşık olarak
+gösterilir.
+
+Widget'ları kendiniz denemek için
+[`Examples/WidgetKitExample/WidgetKitExample.xcodeproj`](Examples/WidgetKitExample) projesini
+açın ve **WidgetKitExample** şemasını bir iPhone simülatöründe çalıştırın;
+[`Examples/README.md`](Examples/README.md) üç widget'ı ve bunları Ana Ekran'a nasıl
+ekleyeceğinizi anlatır.
+
+## Dokümantasyon
+
+API başvuru belgeleri ve makaleler:
+
+- GitHub Pages'te
+ [API başvuru belgeleri](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/);
+ kaynak koddaki DocC yorumlarından üretilir.
+- Xcode'da: **Product › Build Documentation** ya da
+ `xcodebuild docbuild -scheme WidgetDevelopmentKit -destination 'generic/platform=iOS Simulator'`.
+
+## Rehberler
+
+- [Getting Started](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/gettingstarted):
+ widget uzantısını ve paketi ekleme, veriyi App Group üzerinden paylaşma, zaman çizelgesini
+ oluşturma ve bir girişi çizme.
+- [Interactive Widgets](https://muhittincamdali.github.io/iOS-Widget-Development-Kit/documentation/widgetdevelopmentkit/interactivewidgets):
+ App Group'u yapılandırma, intent'leri kaydetme, düğme ekleme ve bunların durumunu
+ sağlayıcıda ve uygulamada okuma.
+
+## Gereksinimler
+
+| Platform | En düşük sürüm |
+| ------------ | -------------- |
+| iOS | 17.0 |
+| macOS | 14.0 |
+| Araç zinciri | Swift 6.0 |
+
+Kilitli Ekran görünümleri ve Live Activities yalnızca iOS'ta vardır. macOS hedefi, platformdan
+bağımsız kod ve testleri `swift test` ile çalışabilsin diye bulunur. CI, GitHub'ın `macos-26`
+imajındaki varsayılan Xcode ile derler; yerel geliştirmede Xcode 27 kullanılır. Daha eski Xcode
+sürümleri denenmedi.
+
+## Mimari
+
+```text
+Sources/WidgetDevelopmentKit/
+├── Core/ Pure helpers: clamping, formatting, month grid, countdown math
+├── Timeline/ Update policy, timeline builder and schedule, snapshot store
+├── Networking/ Data loader with retry policy, endpoint builder
+├── Configuration/ Deep links, hex colors, App Intents entities
+├── Interactive/ App Intents, shared state store, interactive views
+├── Templates/ Home Screen views
+├── Charts/ Swift Charts views
+├── LockScreen/ Accessory family views (iOS)
+├── StandBy/ StandBy views
+├── LiveActivities/ ActivityKit attributes and views (iOS), state machine
+├── UI/ Timeline scrubber
+└── WidgetDevelopmentKit.docc/
+```
+
+Görünümler ince tutulur: gerçek veriyle yanlış gidebilecek hesaplar (sıfır hedefler, `NaN`,
+ters tarih aralıkları, yaz saati geçiş günleri) `Core` ve `Timeline` içinde birim testli saf
+fonksiyonlar olarak durur. Depolamaya ya da ağa dokunan türler bağımlılıklarını
+(`UserDefaults`, saat, taşıma katmanı, bekleme) parametre olarak alır; böylece App Group ya da
+sunucu olmadan test edilebilirler. SwiftUI görünüm gövdeleri için snapshot testi yoktur.
+
+Testleri macOS'ta ve bir iOS simülatöründe çalıştırın:
+
+```sh
+swift test
+xcodebuild test -scheme WidgetDevelopmentKit -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
+```
+
+Üç iOS testi bilerek atlanır: README görsellerini çizerler ve yalnızca
+`scripts/render-screenshots.sh` ile çalışırlar.
+
+## Yol haritası
+
+- Paket sürüm numarasıyla eklenebilsin diye güncel koda karşılık gelen bir sürüm etiketlemek.
+- Görünüm gövdeleri için snapshot testleri.
+- Örnek uygulamaya bir Live Activity örneği.
+
+[CHANGELOG](CHANGELOG.md) şimdiye kadarki değişiklikleri kaydeder; `v1.0.0` kodunun
+derlenmediği anlaşıldıktan sonra paketin Ekim 2026'da nasıl geri getirildiği de buna dahildir.
+
+## Katkıda bulunma
+
+Katkılarınızı bekliyoruz. Pull request açmadan önce [katkı rehberini](https://github.com/muhittincamdali/iOS-Widget-Development-Kit/blob/main/CONTRIBUTING.md) ve [davranış kurallarını](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) okuyun. Güvenlik açıklarını [güvenlik politikasında](https://github.com/muhittincamdali/.github/blob/main/SECURITY.md) anlatıldığı gibi gizli olarak bildirin.
+
+## Lisans
+
+MIT lisansıyla yayımlanmıştır. Ayrıntılar için [LICENSE](LICENSE) dosyasına bakın.
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..4320d60
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,314 @@
+
+
+
+
+
+
+
+
- 
