claudecode-omc 5.6.7 → 5.6.8

package/.local/skills/swiftui-expert-skill/references/focus-patterns.md

@@ -0,0 +1,299 @@
+# SwiftUI Focus Patterns Reference
+
+## Table of Contents
+
+- [@FocusState](#focusstate)
+- [Making Views Focusable](#making-views-focusable)
+- [Focused Values for Commands and Menus](#focused-values-for-commands-and-menus)
+- [Default Focus](#default-focus)
+- [Focus Scope and Sections](#focus-scope-and-sections)
+- [Focus Effects](#focus-effects)
+- [Search Focus](#search-focus)
+- [Common Pitfalls](#common-pitfalls)
+
+## @FocusState
+
+Always mark `@FocusState` as `private`. Use `Bool` for a single field, an optional `Hashable` enum for multiple fields.
+
+### Single field
+
+```swift
+@FocusState private var isFocused: Bool
+
+TextField("Email", text: $email)
+    .focused($isFocused)
+```
+
+### Multiple fields
+
+```swift
+enum Field: Hashable { case name, email, password }
+@FocusState private var focusedField: Field?
+
+TextField("Name", text: $name)
+    .focused($focusedField, equals: .name)
+TextField("Email", text: $email)
+    .focused($focusedField, equals: .email)
+```
+
+Set `focusedField = .email` to move focus programmatically; set `nil` to dismiss the keyboard.
+
+### `focused(_:)` vs `focused(_:equals:)` with nested views
+
+`.focused($bool)` reports `true` when the modified view *or any focusable descendant* has focus. `.focused($enum, equals:)` reports its value only when that specific view receives focus.
+
+```swift
+enum Focus: Hashable { case container, field }
+@FocusState private var focus: Focus?
+
+VStack {
+    TextField("Name", text: $name)
+        .focused($focus, equals: .field)
+}
+.focusable()
+.focused($focus, equals: .container)
+```
+
+With `focused(_:equals:)` and a single `@FocusState`, SwiftUI distinguishes the container *receiving* focus from the container merely *containing* focus.
+
+### `isFocused` environment value
+
+Read-only environment value that returns `true` when the nearest focusable ancestor has focus. Useful for styling non-focusable child views.
+
+```swift
+struct HighlightWrapper: View {
+    @Environment(\.isFocused) private var isFocused
+
+    var body: some View {
+        content
+            .background(isFocused ? Color.accentColor.opacity(0.1) : .clear)
+    }
+}
+```
+
+## Making Views Focusable
+
+### `.focusable(_:)`
+
+Makes a non-text-input view participate in the focus system. Focused views can respond to keyboard events via `onKeyPress` and menu commands like Edit > Delete via `onDeleteCommand`.
+
+```swift
+struct SelectableCard: View {
+    @FocusState private var isFocused: Bool
+
+    var body: some View {
+        CardContent()
+            .focusable()
+            .focused($isFocused)
+            .border(isFocused ? Color.accentColor : .clear)
+            .onDeleteCommand { deleteCard() }
+    }
+}
+```
+
+### `.focusable(_:interactions:)` (iOS 17+)
+
+Controls which focus-driven interactions the view supports via `FocusInteractions`:
+
+- `.activate` -- Button-like: only focusable when system-wide keyboard navigation is on (macOS/iOS)
+- `.edit` -- Captures keyboard/Digital Crown input
+- `.automatic` -- Platform default (both activate and edit)
+
+```swift
+MyTapGestureView(...)
+    .focusable(interactions: .activate)
+```
+
+Use `.activate` for custom button-like views that should match system keyboard-navigation behavior.
+
+## Focused Values for Commands and Menus
+
+Focused values let parent views (App, Scene, Commands) read state from whichever view currently has focus. Use for enabling/disabling menu commands based on the focused document or selection.
+
+### Declare with `@Entry`
+
+```swift
+extension FocusedValues {
+    @Entry var selectedDocument: Binding<Document>?
+}
+```
+
+Focused values are typically optional (default is `nil` when no view publishes them), but you can also use non-optional entries when you have a sensible default value.
+
+### Publish from views
+
+```swift
+// View-scoped: available when this view (or descendant) has focus
+.focusedValue(\.selectedDocument, $document)
+
+// Scene-scoped: available when this scene has focus
+.focusedSceneValue(\.selectedDocument, $document)
+```
+
+### Consume in commands
+
+`@FocusedValue` reads the value; `@FocusedBinding` unwraps a `Binding` automatically.
+
+```swift
+@main
+struct MyApp: App {
+    @FocusedBinding(\.selectedDocument) var document
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+        .commands {
+            CommandGroup(after: .pasteboard) {
+                Button("Duplicate") { document?.duplicate() }
+                    .disabled(document == nil)
+            }
+        }
+    }
+}
+```
+
+### `@FocusedObject` (iOS 16+)
+
+For `ObservableObject` types. The view invalidates when the focused object changes.
+
+```swift
+// Publish
+.focusedObject(myObservableModel)
+
+// Consume
+@FocusedObject var model: MyModel?
+```
+
+Scene-scoped variant: `.focusedSceneObject(_:)`.
+
+## Default Focus
+
+### `.defaultFocus(_:_:priority:)` (iOS 17+, macOS 13+, tvOS 16+)
+
+Prefer `.defaultFocus` over setting `@FocusState` in `onAppear` for initial focus placement.
+
+```swift
+@FocusState private var focusedField: Field?
+
+VStack {
+    TextField("Name", text: $name)
+        .focused($focusedField, equals: .name)
+    TextField("Email", text: $email)
+        .focused($focusedField, equals: .email)
+}
+.defaultFocus($focusedField, .email)
+```
+
+**Priority**: `.automatic` (default) applies on window appearance and programmatic focus changes. `.userInitiated` also applies during user-driven focus navigation.
+
+### `prefersDefaultFocus(_:in:)` (macOS/tvOS/watchOS)
+
+Used with `.focusScope(_:)` to mark a preferred default target within a scoped region.
+
+### `resetFocus` environment action (macOS/tvOS/watchOS)
+
+Re-evaluates default focus within a namespace.
+
+```swift
+@Namespace var scopeID
+@Environment(\.resetFocus) private var resetFocus
+
+Button("Reset") { resetFocus(in: scopeID) }
+```
+
+## Focus Scope and Sections
+
+### `.focusScope(_:)` (macOS/tvOS/watchOS)
+
+Limits default focus preferences to a namespace. Use with `prefersDefaultFocus` and `resetFocus`.
+
+### `.focusSection()` (macOS 13+, tvOS 15+)
+
+Guides directional and sequential focus movement through a group of focusable descendants. Useful when focusable views are spatially separated and directional navigation would otherwise skip them.
+
+```swift
+HStack {
+    VStack { Button("1") {}; Button("2") {}; Spacer() }
+    Spacer()
+    VStack { Spacer(); Button("A") {}; Button("B") {} }
+        .focusSection()
+}
+```
+
+Without `.focusSection()`, swiping right from buttons 1/2 finds nothing. With it, the VStack receives directional focus and delivers it to its first focusable child.
+
+## Focus Effects
+
+### `.focusEffectDisabled(_:)`
+
+Suppresses the system focus ring (macOS) or hover effect. Use when providing custom focus visuals.
+
+```swift
+MyCustomCard()
+    .focusable()
+    .focusEffectDisabled()
+    .overlay { customFocusRing }
+```
+
+`isFocusEffectEnabled` environment value reads the current state.
+
+## Search Focus
+
+### `.searchFocused(_:)` / `.searchFocused(_:equals:)`
+
+Bind focus state to the search field associated with the nearest `.searchable` modifier. Works like `.focused` but targets the search bar.
+
+```swift
+@FocusState private var isSearchFocused: Bool
+
+NavigationStack {
+    ContentView()
+        .searchable(text: $query)
+        .searchFocused($isSearchFocused)
+}
+
+// Programmatically focus the search bar
+Button("Search") { isSearchFocused = true }
+```
+
+## Common Pitfalls
+
+### Redundant `@FocusState` writes revoke focus
+
+`.focusable()` + `.focused()` handles focus-on-click natively. Adding a tap gesture that *also* writes to `@FocusState` triggers a redundant state write, causing a second body evaluation that revokes focus. The result: focus briefly appears then disappears, and key commands like `onDeleteCommand` stop working.
+
+```swift
+// WRONG -- tap gesture redundantly sets focus, causing double evaluation
+CardView()
+    .focusable()
+    .focused($isFocused)
+    .onTapGesture { isFocused = true }  // Remove this line
+
+// CORRECT -- let .focusable() + .focused() handle it
+CardView()
+    .focusable()
+    .focused($isFocused)
+```
+
+### Ambiguous focus bindings
+
+Binding the same enum case to multiple views is ambiguous. SwiftUI picks the first candidate and emits a runtime warning.
+
+```swift
+// WRONG -- .name bound to two views
+TextField("Name", text: $name)
+    .focused($focusedField, equals: .name)
+TextField("Full Name", text: $fullName)
+    .focused($focusedField, equals: .name)  // ambiguous
+```
+
+Always use distinct enum cases for each focusable view.
+
+### `.onAppear` focus timing
+
+Setting `@FocusState` in `.onAppear` may fail if the view tree hasn't settled. Prefer `.defaultFocus` (iOS 17+) for reliable initial focus. If you must use `.onAppear`, wrap in `DispatchQueue.main.async` as a last resort.
+
+### Missing `.focusable()` for non-text views
+
+`TextField` and `SecureField` are implicitly focusable. Custom views (stacks, shapes, images) are not. Forgetting `.focusable()` means `.focused()` bindings have no effect and key event handlers never fire.

package/.local/skills/swiftui-expert-skill/references/image-optimization.md

@@ -0,0 +1,203 @@
+# SwiftUI Image Optimization Reference
+
+## Table of Contents
+
+- [AsyncImage Best Practices](#asyncimage-best-practices)
+- [Image Decoding and Downsampling (Optional Optimization)](#image-decoding-and-downsampling-optional-optimization)
+- [UIImage Loading and Memory](#uiimage-loading-and-memory)
+- [SF Symbols](#sf-symbols)
+- [Summary Checklist](#summary-checklist)
+
+## AsyncImage Best Practices
+
+### Basic AsyncImage with Phase Handling
+
+```swift
+// Good - handles loading and error states
+AsyncImage(url: imageURL) { phase in
+    switch phase {
+    case .empty:
+        ProgressView()
+    case .success(let image):
+        image
+            .resizable()
+            .aspectRatio(contentMode: .fit)
+    case .failure:
+        Image(systemName: "photo")
+            .foregroundStyle(.secondary)
+    @unknown default:
+        EmptyView()
+    }
+}
+.frame(width: 200, height: 200)
+```
+
+For custom placeholders, replace `ProgressView()` in the `.empty` case with your placeholder view. Add `.transition(.opacity)` to the success case and `.animation(.easeInOut, value: imageURL)` to the container for fade-in transitions.
+
+## Image Decoding and Downsampling (Optional Optimization)
+
+**When you encounter `UIImage(data:)` usage, consider suggesting image downsampling as a potential performance improvement**, especially for large images in lists or grids.
+
+### Current Pattern That Could Be Optimized
+
+```swift
+// Current pattern - decodes full image on main thread
+// Unsafe - force unwrap can crash if imageData is invalid
+Image(uiImage: UIImage(data: imageData)!)
+    .resizable()
+    .aspectRatio(contentMode: .fit)
+    .frame(width: 200, height: 200)
+```
+
+### Suggested Optimization Pattern
+
+```swift
+// Suggested optimization - decode and downsample off main thread
+struct OptimizedImageView: View {
+    let imageData: Data
+    let targetSize: CGSize
+    @State private var processedImage: UIImage?
+    
+    var body: some View {
+        Group {
+            if let processedImage {
+                Image(uiImage: processedImage)
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+            } else {
+                ProgressView()
+            }
+        }
+        .task {
+            processedImage = await decodeAndDownsample(imageData, targetSize: targetSize)
+        }
+    }
+    
+    private func decodeAndDownsample(_ data: Data, targetSize: CGSize) async -> UIImage? {
+        await Task.detached {
+            guard let source = CGImageSourceCreateWithData(data as CFData, nil) else {
+                return nil
+            }
+            
+            let options: [CFString: Any] = [
+                kCGImageSourceThumbnailMaxPixelSize: max(targetSize.width, targetSize.height),
+                kCGImageSourceCreateThumbnailFromImageAlways: true,
+                kCGImageSourceCreateThumbnailWithTransform: true
+            ]
+            
+            guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
+                return nil
+            }
+            
+            return UIImage(cgImage: cgImage)
+        }.value
+    }
+}
+
+// Usage
+OptimizedImageView(
+    imageData: imageData,
+    targetSize: CGSize(width: 200, height: 200)
+)
+```
+
+### Reusable Downsampling Actor
+
+For production use, wrap the logic in an `actor` with scale-aware sizing and cache-disabled source options:
+
+```swift
+actor ImageProcessor {
+    func downsample(data: Data, targetSize: CGSize) -> UIImage? {
+        let scale = await UIScreen.main.scale
+        let maxPixel = max(targetSize.width, targetSize.height) * scale
+        let sourceOptions: [CFString: Any] = [kCGImageSourceShouldCache: false]
+        guard let source = CGImageSourceCreateWithData(data as CFData, sourceOptions as CFDictionary) else { return nil }
+        let downsampleOptions: [CFString: Any] = [
+            kCGImageSourceCreateThumbnailFromImageAlways: true,
+            kCGImageSourceThumbnailMaxPixelSize: maxPixel,
+            kCGImageSourceCreateThumbnailWithTransform: true,
+            kCGImageSourceShouldCacheImmediately: true
+        ]
+        guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, downsampleOptions as CFDictionary) else { return nil }
+        return UIImage(cgImage: cgImage)
+    }
+}
+```
+
+Key details: `kCGImageSourceShouldCache: false` on the source prevents the full-resolution image from being cached in memory. Multiplying `targetSize` by `UIScreen.main.scale` ensures the thumbnail is sharp on Retina displays. `kCGImageSourceShouldCacheImmediately: true` on the thumbnail forces decoding at creation time rather than at first render.
+
+### When to Suggest This Optimization
+
+Mention this optimization when you see `UIImage(data:)` usage, particularly in:
+- Scrollable content (List, ScrollView with LazyVStack/LazyHStack)
+- Grid layouts with many images
+- Image galleries or carousels
+- Any scenario where large images are displayed at smaller sizes
+
+**Don't automatically apply it**—present it as an optional improvement for performance-sensitive scenarios.
+
+## UIImage Loading and Memory
+
+### UIImage(named:) Caches in System Cache
+
+`UIImage(named:)` adds images to the system cache, which can cause memory spikes when loading many images (e.g., in a slider or gallery). For single-use or frequently-rotated images, use `UIImage(contentsOfFile:)` to bypass the cache:
+
+```swift
+// Caches in system cache -- memory builds up
+let image = UIImage(named: "Wallpapers/image_001.jpg")
+
+// No system caching -- memory stays flat
+guard let path = Bundle.main.path(forResource: "Wallpapers/image_001.jpg", ofType: nil) else { return nil }
+let image = UIImage(contentsOfFile: path)
+```
+
+### NSCache for Controlled Image Caching
+
+When image processing (resizing, filtering) is needed, use `NSCache` with a `countLimit` to bound memory instead of relying on system caching:
+
+```swift
+struct ImageCache {
+    private let cache = NSCache<NSString, UIImage>()
+
+    init(countLimit: Int = 50) {
+        cache.countLimit = countLimit
+    }
+
+    subscript(key: String) -> UIImage? {
+        get { cache.object(forKey: key as NSString) }
+        nonmutating set {
+            if let newValue {
+                cache.setObject(newValue, forKey: key as NSString)
+            } else {
+                cache.removeObject(forKey: key as NSString)
+            }
+        }
+    }
+}
+```
+
+## SF Symbols
+
+```swift
+Image(systemName: "star.fill")
+    .foregroundStyle(.yellow)
+    .symbolRenderingMode(.multicolor)     // or .hierarchical, .palette, .monochrome
+
+// Animated symbols (iOS 17+)
+Image(systemName: "antenna.radiowaves.left.and.right")
+    .symbolEffect(.variableColor)
+```
+
+Variants are available via naming convention: `star.circle.fill`, `star.square.fill`, `folder.badge.plus`.
+
+## Summary Checklist
+
+- [ ] Use `AsyncImage` with proper phase handling
+- [ ] Handle empty, success, and failure states
+- [ ] Consider downsampling for `UIImage(data:)` in performance-sensitive scenarios
+- [ ] Decode and downsample images off the main thread
+- [ ] Use appropriate target sizes for downsampling
+- [ ] Consider image caching for frequently accessed images
+- [ ] Use SF Symbols with appropriate rendering modes
+
+**Performance Note**: Image downsampling is an optional optimization. Only suggest it when you encounter `UIImage(data:)` usage in performance-sensitive contexts like scrollable lists or grids.