opencodekit 0.16.15 → 0.16.17

package/dist/template/.opencode/skill/swiftui-expert-skill/references/liquid-glass.md

@@ -0,0 +1,377 @@
+# SwiftUI Liquid Glass Reference (iOS 26+)
+
+## Overview
+
+Liquid Glass is Apple's new design language introduced in iOS 26. It provides translucent, dynamic surfaces that respond to content and user interaction. This reference covers the native SwiftUI APIs for implementing Liquid Glass effects.
+
+## Availability
+
+All Liquid Glass APIs require iOS 26 or later. Always provide fallbacks:
+
+```swift
+if #available(iOS 26, *) {
+    // Liquid Glass implementation
+} else {
+    // Fallback using materials
+}
+```
+
+## Core APIs
+
+### glassEffect Modifier
+
+The primary modifier for applying glass effects to views:
+
+```swift
+.glassEffect(_ style: GlassEffectStyle = .regular, in shape: some Shape = .rect)
+```
+
+#### Basic Usage
+
+```swift
+Text("Hello")
+    .padding()
+    .glassEffect()  // Default regular style, rect shape
+```
+
+#### With Shape
+
+```swift
+Text("Rounded Glass")
+    .padding()
+    .glassEffect(in: .rect(cornerRadius: 16))
+
+Image(systemName: "star")
+    .padding()
+    .glassEffect(in: .circle)
+
+Text("Capsule")
+    .padding(.horizontal, 20)
+    .padding(.vertical, 10)
+    .glassEffect(in: .capsule)
+```
+
+### GlassEffectStyle
+
+#### Prominence Levels
+
+```swift
+.glassEffect(.regular)     // Standard glass appearance
+.glassEffect(.prominent)   // More visible, higher contrast
+```
+
+#### Tinting
+
+Add color tint to the glass:
+
+```swift
+.glassEffect(.regular.tint(.blue))
+.glassEffect(.prominent.tint(.red.opacity(0.3)))
+```
+
+#### Interactivity
+
+Make glass respond to touch/pointer hover:
+
+```swift
+// Interactive glass - responds to user interaction
+.glassEffect(.regular.interactive())
+
+// Combined with tint
+.glassEffect(.regular.tint(.blue).interactive())
+```
+
+**Important**: Only use `.interactive()` on elements that actually respond to user input (buttons, tappable views, focusable elements).
+
+## GlassEffectContainer
+
+Wraps multiple glass elements for proper visual grouping and spacing:
+
+```swift
+GlassEffectContainer {
+    HStack {
+        Button("One") { }
+            .glassEffect()
+        Button("Two") { }
+            .glassEffect()
+    }
+}
+```
+
+### With Spacing
+
+Control the visual spacing between glass elements:
+
+```swift
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassChip(icon: "pencil")
+        GlassChip(icon: "eraser")
+        GlassChip(icon: "trash")
+    }
+}
+```
+
+**Note**: The container's `spacing` parameter should match the actual spacing in your layout for proper glass effect rendering.
+
+## Glass Button Styles
+
+Built-in button styles for glass appearance:
+
+```swift
+// Standard glass button
+Button("Action") { }
+    .buttonStyle(.glass)
+
+// Prominent glass button (higher visibility)
+Button("Primary Action") { }
+    .buttonStyle(.glassProminent)
+```
+
+### Custom Glass Buttons
+
+For more control, apply glass effect manually:
+
+```swift
+Button(action: { }) {
+    Label("Settings", systemImage: "gear")
+        .padding()
+}
+.glassEffect(.regular.interactive(), in: .capsule)
+```
+
+## Morphing Transitions
+
+Create smooth transitions between glass elements using `glassEffectID` and `@Namespace`:
+
+```swift
+struct MorphingExample: View {
+    @Namespace private var animation
+    @State private var isExpanded = false
+
+    var body: some View {
+        GlassEffectContainer {
+            if isExpanded {
+                ExpandedCard()
+                    .glassEffect()
+                    .glassEffectID("card", in: animation)
+            } else {
+                CompactCard()
+                    .glassEffect()
+                    .glassEffectID("card", in: animation)
+            }
+        }
+        .animation(.smooth, value: isExpanded)
+    }
+}
+```
+
+### Requirements for Morphing
+
+1. Both views must have the same `glassEffectID`
+2. Use the same `@Namespace`
+3. Wrap in `GlassEffectContainer`
+4. Apply animation to the container or parent
+
+## Modifier Order
+
+**Critical**: Apply `glassEffect` after layout and visual modifiers:
+
+```swift
+// CORRECT order
+Text("Label")
+    .font(.headline)           // 1. Typography
+    .foregroundStyle(.primary) // 2. Color
+    .padding()                 // 3. Layout
+    .glassEffect()             // 4. Glass effect LAST
+
+// WRONG order - glass applied too early
+Text("Label")
+    .glassEffect()             // Wrong position
+    .padding()
+    .font(.headline)
+```
+
+## Complete Examples
+
+### Toolbar with Glass Buttons
+
+```swift
+struct GlassToolbar: View {
+    var body: some View {
+        if #available(iOS 26, *) {
+            GlassEffectContainer(spacing: 16) {
+                HStack(spacing: 16) {
+                    ToolbarButton(icon: "pencil", action: { })
+                    ToolbarButton(icon: "eraser", action: { })
+                    ToolbarButton(icon: "scissors", action: { })
+                    Spacer()
+                    ToolbarButton(icon: "square.and.arrow.up", action: { })
+                }
+                .padding(.horizontal)
+            }
+        } else {
+            // Fallback toolbar
+            HStack(spacing: 16) {
+                // ... fallback implementation
+            }
+        }
+    }
+}
+
+struct ToolbarButton: View {
+    let icon: String
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: action) {
+            Image(systemName: icon)
+                .font(.title2)
+                .frame(width: 44, height: 44)
+        }
+        .glassEffect(.regular.interactive(), in: .circle)
+    }
+}
+```
+
+### Card with Glass Effect
+
+```swift
+struct GlassCard: View {
+    let title: String
+    let subtitle: String
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            cardContent
+                .glassEffect(.regular, in: .rect(cornerRadius: 20))
+        } else {
+            cardContent
+                .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 20))
+        }
+    }
+
+    private var cardContent: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text(title)
+                .font(.headline)
+            Text(subtitle)
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+        }
+        .padding()
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+}
+```
+
+### Segmented Control
+
+```swift
+struct GlassSegmentedControl: View {
+    @Binding var selection: Int
+    let options: [String]
+    @Namespace private var animation
+
+    var body: some View {
+        if #available(iOS 26, *) {
+            GlassEffectContainer(spacing: 4) {
+                HStack(spacing: 4) {
+                    ForEach(options.indices, id: \.self) { index in
+                        Button(options[index]) {
+                            withAnimation(.smooth) {
+                                selection = index
+                            }
+                        }
+                        .padding(.horizontal, 16)
+                        .padding(.vertical, 8)
+                        .glassEffect(
+                            selection == index ? .prominent.interactive() : .regular.interactive(),
+                            in: .capsule
+                        )
+                        .glassEffectID(selection == index ? "selected" : "option\(index)", in: animation)
+                    }
+                }
+                .padding(4)
+            }
+        } else {
+            Picker("Options", selection: $selection) {
+                ForEach(options.indices, id: \.self) { index in
+                    Text(options[index]).tag(index)
+                }
+            }
+            .pickerStyle(.segmented)
+        }
+    }
+}
+```
+
+## Fallback Strategies
+
+### Using Materials
+
+```swift
+if #available(iOS 26, *) {
+    content.glassEffect()
+} else {
+    content.background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+```
+
+### Available Materials for Fallback
+
+- `.ultraThinMaterial` - Closest to glass appearance
+- `.thinMaterial` - Slightly more opaque
+- `.regularMaterial` - Standard blur
+- `.thickMaterial` - More opaque
+- `.ultraThickMaterial` - Most opaque
+
+### Conditional Modifier Extension
+
+```swift
+extension View {
+    @ViewBuilder
+    func glassEffectWithFallback(
+        _ style: GlassEffectStyle = .regular,
+        in shape: some Shape = .rect,
+        fallbackMaterial: Material = .ultraThinMaterial
+    ) -> some View {
+        if #available(iOS 26, *) {
+            self.glassEffect(style, in: shape)
+        } else {
+            self.background(fallbackMaterial, in: shape)
+        }
+    }
+}
+```
+
+## Best Practices
+
+### Do
+
+- Use `GlassEffectContainer` for grouped glass elements
+- Apply glass after layout modifiers
+- Use `.interactive()` only on tappable elements
+- Match container spacing with layout spacing
+- Provide material-based fallbacks for older iOS
+- Keep glass shapes consistent within a feature
+
+### Don't
+
+- Apply glass to every element (use sparingly)
+- Use `.interactive()` on static content
+- Mix different corner radii arbitrarily
+- Forget iOS version checks
+- Apply glass before padding/frame modifiers
+- Nest `GlassEffectContainer` unnecessarily
+
+## Checklist
+
+- [ ] `#available(iOS 26, *)` with fallback
+- [ ] `GlassEffectContainer` wraps grouped elements
+- [ ] `.glassEffect()` applied after layout modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] `glassEffectID` with `@Namespace` for morphing
+- [ ] Consistent shapes and spacing across feature
+- [ ] Container spacing matches layout spacing
+- [ ] Appropriate prominence levels used

package/dist/template/.opencode/skill/swiftui-expert-skill/references/list-patterns.md

@@ -0,0 +1,153 @@
+# SwiftUI List Patterns Reference
+
+## ForEach Identity and Stability
+
+**Always provide stable identity for `ForEach`.** Never use `.indices` for dynamic content.
+
+```swift
+// Good - stable identity via Identifiable
+extension User: Identifiable {
+    var id: String { userId }
+}
+
+ForEach(users) { user in
+    UserRow(user: user)
+}
+
+// Good - stable identity via keypath
+ForEach(users, id: \.userId) { user in
+    UserRow(user: user)
+}
+
+// Wrong - indices create static content
+ForEach(users.indices, id: \.self) { index in
+    UserRow(user: users[index])  // Can crash on removal!
+}
+
+// Wrong - unstable identity
+ForEach(users, id: \.self) { user in
+    UserRow(user: user)  // Only works if User is Hashable and stable
+}
+```
+
+**Critical**: Ensure **constant number of views per element** in `ForEach`:
+
+```swift
+// Good - consistent view count
+ForEach(items) { item in
+    ItemRow(item: item)
+}
+
+// Bad - variable view count breaks identity
+ForEach(items) { item in
+    if item.isSpecial {
+        SpecialRow(item: item)
+        DetailRow(item: item)
+    } else {
+        RegularRow(item: item)
+    }
+}
+```
+
+**Avoid inline filtering:**
+
+```swift
+// Bad - unstable identity, changes on every update
+ForEach(items.filter { $0.isEnabled }) { item in
+    ItemRow(item: item)
+}
+
+// Good - prefilter and cache
+@State private var enabledItems: [Item] = []
+
+var body: some View {
+    ForEach(enabledItems) { item in
+        ItemRow(item: item)
+    }
+    .onChange(of: items) { _, newItems in
+        enabledItems = newItems.filter { $0.isEnabled }
+    }
+}
+```
+
+**Avoid `AnyView` in list rows:**
+
+```swift
+// Bad - hides identity, increases cost
+ForEach(items) { item in
+    AnyView(item.isSpecial ? SpecialRow(item: item) : RegularRow(item: item))
+}
+
+// Good - Create a unified row view
+ForEach(items) { item in
+    ItemRow(item: item)
+}
+
+struct ItemRow: View {
+    let item: Item
+
+    var body: some View {
+        if item.isSpecial {
+            SpecialRow(item: item)
+        } else {
+            RegularRow(item: item)
+        }
+    }
+}
+```
+
+**Why**: Stable identity is critical for performance and animations. Unstable identity causes excessive diffing, broken animations, and potential crashes.
+
+## Enumerated Sequences
+
+**Always convert enumerated sequences to arrays. To be able to use them in a ForEach.**
+
+```swift
+let items = ["A", "B", "C"]
+
+// Correct
+ForEach(Array(items.enumerated()), id: \.offset) { index, item in
+    Text("\(index): \(item)")
+}
+
+// Wrong - Doesn't compile, enumerated() isn't an array
+ForEach(items.enumerated(), id: \.offset) { index, item in
+    Text("\(index): \(item)")
+}
+```
+
+## List with Custom Styling
+
+```swift
+// Remove default background and separators
+List(items) { item in
+    ItemRow(item: item)
+        .listRowInsets(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
+        .listRowSeparator(.hidden)
+}
+.listStyle(.plain)
+.scrollContentBackground(.hidden)
+.background(Color.customBackground)
+.environment(\.defaultMinListRowHeight, 1)  // Allows custom row heights
+```
+
+## List with Pull-to-Refresh
+
+```swift
+List(items) { item in
+    ItemRow(item: item)
+}
+.refreshable {
+    await loadItems()
+}
+```
+
+## Summary Checklist
+
+- [ ] ForEach uses stable identity (never `.indices` for dynamic content)
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach (prefilter and cache instead)
+- [ ] No `AnyView` in list rows
+- [ ] Don't convert enumerated sequences to arrays
+- [ ] Use `.refreshable` for pull-to-refresh
+- [ ] Custom list styling uses appropriate modifiers