existential-birds/beagle / plugins/beagle-ios/skills/widgetkit-code-review
widgetkit-code-review
VerifiedReviews WidgetKit code for timeline management, view composition, configurable intents, and performance. Use when reviewing code with import WidgetKit, TimelineProvider, Widget protocol, or @main struct Widget.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.6 KB |
| references/intents.md | markdown | 4.1 KB |
| references/performance.md | markdown | 4.5 KB |
| references/timeline.md | markdown | 4.2 KB |
| references/views.md | markdown | 2.9 KB |
references/intents.md
View on GitHub# Configurable Widgets
## Configuration Approaches
| Approach | iOS | Status |
|----------|-----|--------|
| `StaticConfiguration` | 14+ | Non-configurable widgets |
| `IntentConfiguration` | 14+ | Legacy SiriKit intents |
| `AppIntentConfiguration` | 17+ | Modern App Intents |
**Migration warning**: Changing from `IntentConfiguration` to `AppIntentConfiguration` can cause existing user widgets to disappear or freeze.
## AppIntentTimelineProvider
```swift
struct ConfigurableProvider: AppIntentTimelineProvider {
func placeholder(in context: Context) -> MyEntry { .placeholder } // Sync, instant
func snapshot(for config: MyIntent, in context: Context) async -> MyEntry {
MyEntry(date: .now, item: config.selectedItem)
}
func timeline(for config: MyIntent, in context: Context) async -> Timeline<MyEntry> {
let entry = MyEntry(date: .now, item: config.selectedItem)
return Timeline(entries: [entry], policy: .after(.now.addingTimeInterval(900)))
}
}
```
## Widget Configuration
```swift
struct MyWidgetIntent: WidgetConfigurationIntent {
static var title: LocalizedStringResource = "Configure Widget"
@Parameter(title: "Name", default: "Default") var name: String
@Parameter(title: "Style") var style: DisplayStyle // AppEnum
@Parameter(title: "Item") var selectedItem: ItemEntity? // AppEntity
}
struct MyWidget: Widget {
var body: some WidgetConfiguration {
AppIntentConfiguration(kind: "com.app.widget", intent: MyWidgetIntent.self,
provider: ConfigurableProvider()) { entry in
MyWidgetView(entry: entry)
}
}
}
```
## Dynamic Options
### EntityStringQuery for Custom Types
```swift
struct ItemEntity: AppEntity {
static var defaultQuery = ItemQuery()
var id: String
var name: String
var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }
}
struct ItemQuery: EntityStringQuery {
func entities(for identifiers: [String]) async throws -> [ItemEntity] { /* fetch by IDs */ }
func entities(matching string: String) async throws -> [ItemEntity] { /* search */ }
func suggestedEntities() async throws -> [ItemEntity] { /* default list */ }
func defaultResult() async -> ItemEntity? { /* REQUIRED for non-optional params */ }
}
```
### DynamicOptionsProvider for Simple Types
```swift
@Parameter(title: "Hour", optionsProvider: HourOptionsProvider()) var hour: Int
struct HourOptionsProvider: DynamicOptionsProvider {
func results() async throws -> [Int] { Array(0..<24) }
func defaultResult() async -> Int? { 12 }
}
```
## Critical Anti-Patterns
### Missing defaultResult()
```swift
// BAD: Widget shows "Select" instead of value
struct ItemQuery: EntityStringQuery { /* no defaultResult() */ }
// GOOD: Always implement for non-optional entity parameters
func defaultResult() async -> ItemEntity? { items.first }
```
### Ignoring Nil After App Updates
```swift
// BAD: Parameters added in updates are nil for existing widgets
let name = config.newParameter.name // Crash!
// GOOD: Handle optional parameters
let name = config.newParameter?.name ?? "Default"
```
### Heavy Work in Placeholder
```swift
// BAD: Blocks UI
func placeholder(in context: Context) -> Entry { Entry(data: fetchSync()) }
// GOOD: Return static data instantly
func placeholder(in context: Context) -> Entry { .placeholder }
```
### Breaking Migration
```swift
// BAD: Same kind causes widget disappearance
AppIntentConfiguration(kind: "widget", ...) // Was IntentConfiguration
// GOOD: Use new kind for new configuration type
AppIntentConfiguration(kind: "widget.v2", ...)
```
## Review Questions
1. **Does EntityQuery implement `defaultResult()`?** Missing causes "Select" UI instead of default.
2. **Are new parameters optional-safe?** Parameters added in updates are nil for existing widgets.
3. **Is placeholder instant?** Must be synchronous with static data only.
4. **Does migration use new kind?** Same kind string breaks existing widgets.
5. **Is configuration stored in timeline entry?** Entry must hold intent for view access.
6. **Are AppEntity types Codable?** Required for WidgetKit to persist configuration.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |