codexkit 1.0.0

package/.codex/skills/swiftui-expert-skill/references/text-formatting.md

@@ -0,0 +1,285 @@
+# SwiftUI Text Formatting Reference
+
+## Modern Text Formatting
+
+**Never use C-style `String(format:)` with Text. Always use format parameters.**
+
+## Number Formatting
+
+### Basic Number Formatting
+
+```swift
+let value = 42.12345
+
+// Modern (Correct)
+Text(value, format: .number.precision(.fractionLength(2)))
+// Output: "42.12"
+
+Text(abs(value), format: .number.precision(.fractionLength(2)))
+// Output: "42.12" (absolute value)
+
+// Legacy (Avoid)
+Text(String(format: "%.2f", abs(value)))
+```
+
+### Integer Formatting
+
+```swift
+let count = 1234567
+
+// With grouping separator
+Text(count, format: .number)
+// Output: "1,234,567" (locale-dependent)
+
+// Without grouping
+Text(count, format: .number.grouping(.never))
+// Output: "1234567"
+```
+
+### Decimal Precision
+
+```swift
+let price = 19.99
+
+// Fixed decimal places
+Text(price, format: .number.precision(.fractionLength(2)))
+// Output: "19.99"
+
+// Significant digits
+Text(price, format: .number.precision(.significantDigits(3)))
+// Output: "20.0"
+
+// Integer-only
+Text(price, format: .number.precision(.integerLength(1...)))
+// Output: "19"
+```
+
+## Currency Formatting
+
+```swift
+let price = 19.99
+
+// Correct - with currency code
+Text(price, format: .currency(code: "USD"))
+// Output: "$19.99"
+
+// With locale
+Text(price, format: .currency(code: "EUR").locale(Locale(identifier: "de_DE")))
+// Output: "19,99 €"
+
+// Avoid - manual formatting
+Text(String(format: "$%.2f", price))
+```
+
+## Percentage Formatting
+
+```swift
+let percentage = 0.856
+
+// Correct - with precision
+Text(percentage, format: .percent.precision(.fractionLength(1)))
+// Output: "85.6%"
+
+// Without decimal places
+Text(percentage, format: .percent.precision(.fractionLength(0)))
+// Output: "86%"
+
+// Avoid - manual calculation
+Text(String(format: "%.1f%%", percentage * 100))
+```
+
+## Date and Time Formatting
+
+### Date Formatting
+
+```swift
+let date = Date()
+
+// Date only
+Text(date, format: .dateTime.day().month().year())
+// Output: "Jan 23, 2026"
+
+// Full date
+Text(date, format: .dateTime.day().month(.wide).year())
+// Output: "January 23, 2026"
+
+// Short date
+Text(date, style: .date)
+// Output: "1/23/26"
+```
+
+### Time Formatting
+
+```swift
+let date = Date()
+
+// Time only
+Text(date, format: .dateTime.hour().minute())
+// Output: "2:30 PM"
+
+// With seconds
+Text(date, format: .dateTime.hour().minute().second())
+// Output: "2:30:45 PM"
+
+// 24-hour format
+Text(date, format: .dateTime.hour(.defaultDigits(amPM: .omitted)).minute())
+// Output: "14:30"
+```
+
+### Relative Date Formatting
+
+```swift
+let futureDate = Date().addingTimeInterval(3600)
+
+// Relative formatting
+Text(futureDate, style: .relative)
+// Output: "in 1 hour"
+
+Text(futureDate, style: .timer)
+// Output: "59:59" (counts down)
+```
+
+## String Searching and Comparison
+
+### Localized String Comparison
+
+**Use `localizedStandardContains()` for user-input filtering, not `contains()`.**
+
+```swift
+let searchText = "café"
+let items = ["Café Latte", "Coffee", "Tea"]
+
+// Correct - handles diacritics and case
+let filtered = items.filter { $0.localizedStandardContains(searchText) }
+// Matches "Café Latte"
+
+// Wrong - exact match only
+let filtered = items.filter { $0.contains(searchText) }
+// Might not match "Café Latte" depending on normalization
+```
+
+**Why**: `localizedStandardContains()` handles case-insensitive, diacritic-insensitive matching appropriate for user-facing search.
+
+### Case-Insensitive Comparison
+
+```swift
+let text = "Hello World"
+let search = "hello"
+
+// Correct - case-insensitive
+if text.localizedCaseInsensitiveContains(search) {
+    // Match found
+}
+
+// Also correct - for exact comparison
+if text.lowercased() == search.lowercased() {
+    // Equal
+}
+```
+
+### Localized Sorting
+
+```swift
+let names = ["Zoë", "Zara", "Åsa"]
+
+// Correct - locale-aware sorting
+let sorted = names.sorted { $0.localizedStandardCompare($1) == .orderedAscending }
+// Output: ["Åsa", "Zara", "Zoë"]
+
+// Wrong - byte-wise sorting
+let sorted = names.sorted()
+// Output may not be correct for all locales
+```
+
+## Attributed Strings
+
+### Basic Attributed Text
+
+```swift
+// Using Text concatenation
+Text("Hello ")
+    .foregroundStyle(.primary)
++ Text("World")
+    .foregroundStyle(.blue)
+    .bold()
+
+// Using AttributedString
+var attributedString = AttributedString("Hello World")
+attributedString.foregroundColor = .primary
+if let range = attributedString.range(of: "World") {
+    attributedString[range].foregroundColor = .blue
+    attributedString[range].font = .body.bold()
+}
+Text(attributedString)
+```
+
+### Markdown in Text
+
+```swift
+// Simple markdown
+Text("This is **bold** and this is *italic*")
+
+// With links
+Text("Visit [Apple](https://apple.com) for more info")
+
+// Multiline markdown
+Text("""
+# Title
+This is a paragraph with **bold** text.
+- Item 1
+- Item 2
+""")
+```
+
+## Text Measurement
+
+### Measuring Text Height
+
+```swift
+// Wrong (Legacy) - GeometryReader trick
+struct MeasuredText: View {
+    let text: String
+    @State private var textHeight: CGFloat = 0
+    
+    var body: some View {
+        Text(text)
+            .background(
+                GeometryReader { geometry in
+                    Color.clear
+                        .onAppear {
+                            textWidth = geometry.size.height
+                        }
+                }
+            )
+    }
+}
+
+// Modern (correct)
+struct MeasuredText: View {
+    let text: String
+    @State private var textHeight: CGFloat = 0
+    
+    var body: some View {
+        Text(text)
+            .onGeometryChange(for: CGFloat.self) { geometry in
+                geometry.size.height
+            } action: { newValue in
+                textHeight = newValue
+            }
+    }
+}
+```
+
+## Summary Checklist
+
+- [ ] Use `.format` parameters with Text instead of `String(format:)`
+- [ ] Use `.currency(code:)` for currency formatting
+- [ ] Use `.percent` for percentage formatting
+- [ ] Use `.dateTime` for date/time formatting
+- [ ] Use `localizedStandardContains()` for user-input search
+- [ ] Use `localizedStandardCompare()` for locale-aware sorting
+- [ ] Use Text concatenation or AttributedString for styled text
+- [ ] Use markdown syntax for simple text formatting
+- [ ] All formatting respects user's locale and preferences
+
+**Why**: Modern format parameters are type-safe, localization-aware, and integrate better with SwiftUI's text rendering.

package/.codex/skills/swiftui-expert-skill/references/view-structure.md

@@ -0,0 +1,276 @@
+# SwiftUI View Structure Reference
+
+## View Structure Principles
+
+SwiftUI's diffing algorithm compares view hierarchies to determine what needs updating. Proper view composition directly impacts performance.
+
+## Prefer Modifiers Over Conditional Views
+
+**Prefer "no-effect" modifiers over conditionally including views.** When you introduce a branch, consider whether you're representing multiple views or two states of the same view.
+
+### Use Opacity Instead of Conditional Inclusion
+
+```swift
+// Good - same view, different states
+SomeView()
+    .opacity(isVisible ? 1 : 0)
+
+// Avoid - creates/destroys view identity
+if isVisible {
+    SomeView()
+}
+```
+
+**Why**: Conditional view inclusion can cause loss of state, poor animation performance, and breaks view identity. Using modifiers maintains view identity across state changes.
+
+### When Conditionals Are Appropriate
+
+Use conditionals when you truly have **different views**, not different states:
+
+```swift
+// Correct - fundamentally different views
+if isLoggedIn {
+    DashboardView()
+} else {
+    LoginView()
+}
+
+// Correct - optional content
+if let user {
+    UserProfileView(user: user)
+}
+```
+
+## Extract Subviews, Not Computed Properties
+
+### The Problem with @ViewBuilder Functions
+
+When you use `@ViewBuilder` functions or computed properties for complex views, the entire function re-executes on every parent state change:
+
+```swift
+// BAD - re-executes complexSection() on every tap
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            complexSection()  // Re-executes every tap!
+        }
+    }
+
+    @ViewBuilder
+    func complexSection() -> some View {
+        // Complex views that re-execute unnecessarily
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### The Solution: Separate Structs
+
+Extract to separate `struct` views. SwiftUI can skip their `body` when inputs don't change:
+
+```swift
+// GOOD - ComplexSection body SKIPPED when its inputs don't change
+struct ParentView: View {
+    @State private var count = 0
+
+    var body: some View {
+        VStack {
+            Button("Tap: \(count)") { count += 1 }
+            ComplexSection()  // Body skipped during re-evaluation
+        }
+    }
+}
+
+struct ComplexSection: View {
+    var body: some View {
+        ForEach(0..<100) { i in
+            HStack {
+                Image(systemName: "star")
+                Text("Item \(i)")
+                Spacer()
+                Text("Detail")
+            }
+        }
+    }
+}
+```
+
+### Why This Works
+
+1. SwiftUI compares the `ComplexSection` struct (which has no properties)
+2. Since nothing changed, SwiftUI skips calling `ComplexSection.body`
+3. The complex view code never executes unnecessarily
+
+## When @ViewBuilder Functions Are Acceptable
+
+Use for small, simple sections that don't affect performance:
+
+```swift
+struct SimpleView: View {
+    @State private var showDetails = false
+
+    var body: some View {
+        VStack {
+            headerSection()  // OK - simple, few views
+            if showDetails {
+                detailsSection()
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func headerSection() -> some View {
+        HStack {
+            Text("Title")
+            Spacer()
+            Button("Toggle") { showDetails.toggle() }
+        }
+    }
+
+    @ViewBuilder
+    private func detailsSection() -> some View {
+        Text("Some details here")
+            .font(.caption)
+    }
+}
+```
+
+## When to Extract Subviews
+
+Extract complex views into separate subviews when:
+- The view has multiple logical sections or responsibilities
+- The view contains reusable components
+- The view body becomes difficult to read or understand
+- You need to isolate state changes for performance
+- The view is becoming large (keep views small for better performance)
+
+## Container View Pattern
+
+### Avoid Closure-Based Content
+
+Closures can't be compared, causing unnecessary re-renders:
+
+```swift
+// BAD - closure prevents SwiftUI from skipping updates
+struct MyContainer<Content: View>: View {
+    let content: () -> Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content()  // Always called, can't compare closures
+        }
+    }
+}
+
+// Usage forces re-render on every parent update
+MyContainer {
+    ExpensiveView()
+}
+```
+
+### Use @ViewBuilder Property Instead
+
+```swift
+// GOOD - view can be compared
+struct MyContainer<Content: View>: View {
+    @ViewBuilder let content: Content
+
+    var body: some View {
+        VStack {
+            Text("Header")
+            content  // SwiftUI can compare and skip if unchanged
+        }
+    }
+}
+
+// Usage - SwiftUI can diff ExpensiveView
+MyContainer {
+    ExpensiveView()
+}
+```
+
+## ZStack vs overlay/background
+
+Use `ZStack` to **compose multiple peer views** that should be layered together and jointly define layout.
+
+Prefer `overlay` / `background` when you’re **decorating a primary view**.  
+Not primarily because they don’t affect layout size, but because they **express intent and improve readability**: the view being modified remains the clear layout anchor.
+
+A key difference is **size proposal behavior**:
+- In `overlay` / `background`, the child view implicitly adopts the size proposed to the parent when it doesn’t define its own size, making decorative attachments feel natural and predictable.
+- In `ZStack`, each child participates independently in layout, and no implicit size inheritance exists. This makes it better suited for peer composition, but less intuitive for simple decoration.
+
+Use `ZStack` (or another container) when the “decoration” **must explicitly participate in layout sizing**—for example, when reserving space, extending tappable/visible bounds, or preventing overlap with neighboring views.
+
+### Examples: Choosing Between overlay/background and ZStack
+
+```swift
+// GOOD - correct usage
+// Decoration that should not change layout sizing belongs in overlay/background
+Button("Continue") {
+    // action
+}
+.overlay(alignment: .trailing) {
+    Image(systemName: "lock.fill")
+        .padding(.trailing, 8)
+}
+
+// BAD - incorrect usage
+// Using ZStack when overlay/background is enough and layout sizing should remain anchored to the button
+ZStack(alignment: .trailing) {
+    Button("Continue") {
+        // action
+    }
+    Image(systemName: "lock.fill")
+        .padding(.trailing, 8)
+}
+
+// GOOD - correct usage
+// Capsule is taking a parent size for rendering
+HStack(spacing: 12) {
+    HStack {
+        Image(systemName: "tray")
+        Text("Inbox")
+    }
+    Text("Next")
+}
+.background {
+    Capsule()
+        .strokeBorder(.blue, lineWidth: 2)
+}
+
+// BAD - incorrect usage
+// overlay does not contribute to measured size, so the Capsule is taking all available space if no explicit size is set
+ZStack(alignment: .topTrailing) {
+    HStack(spacing: 12) {
+        HStack {
+            Image(systemName: "tray")
+            Text("Inbox")
+        }
+        Text("Next")
+    }
+
+    Capsule()
+        .strokeBorder(.blue, lineWidth: 2)
+}
+```
+
+## Summary Checklist
+
+- [ ] Prefer modifiers over conditional views for state changes
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for better performance
+- [ ] `@ViewBuilder` functions only for simple sections
+- [ ] Container views use `@ViewBuilder let content: Content`
+- [ ] Extract views when they have multiple responsibilities or become hard to read