buildanything 1.7.0 → 1.8.0

package/skills/ios/swiftui-ui-patterns/references/deeplinks.md

@@ -0,0 +1,66 @@
+# Deep links and navigation
+
+## Intent
+
+Route external URLs into in-app destinations while falling back to system handling when needed.
+
+## Core patterns
+
+- Centralize URL handling in the router (`handle(url:)`, `handleDeepLink(url:)`).
+- Inject an `OpenURLAction` handler that delegates to the router.
+- Use `.onOpenURL` for app scheme links and convert them to web URLs if needed.
+- Let the router decide whether to navigate or open externally.
+
+## Example: router entry points
+
+```swift
+@MainActor
+final class RouterPath {
+  var path: [Route] = []
+  var urlHandler: ((URL) -> OpenURLAction.Result)?
+
+  func handle(url: URL) -> OpenURLAction.Result {
+    if isInternal(url) {
+      navigate(to: .status(id: url.lastPathComponent))
+      return .handled
+    }
+    return urlHandler?(url) ?? .systemAction
+  }
+
+  func handleDeepLink(url: URL) -> OpenURLAction.Result {
+    // Resolve federated URLs, then navigate.
+    navigate(to: .status(id: url.lastPathComponent))
+    return .handled
+  }
+}
+```
+
+## Example: attach to a root view
+
+```swift
+extension View {
+  func withLinkRouter(_ router: RouterPath) -> some View {
+    self
+      .environment(
+        \.openURL,
+        OpenURLAction { url in
+          router.handle(url: url)
+        }
+      )
+      .onOpenURL { url in
+        router.handleDeepLink(url: url)
+      }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep URL parsing and decision logic inside the router.
+- Avoid handling deep links in multiple places; one entry point is enough.
+- Always provide a fallback to `OpenURLAction` or `UIApplication.shared.open`.
+
+## Pitfalls
+
+- Don’t assume the URL is internal; validate first.
+- Avoid blocking UI while resolving remote links; use `Task`.

package/skills/ios/swiftui-ui-patterns/references/focus.md

@@ -0,0 +1,90 @@
+# Focus handling and field chaining
+
+## Intent
+
+Use `@FocusState` to control keyboard focus, chain fields, and coordinate focus across complex forms.
+
+## Core patterns
+
+- Use an enum to represent focusable fields.
+- Set initial focus in `onAppear`.
+- Use `.onSubmit` to move focus to the next field.
+- For dynamic lists of fields, use an enum with associated values (e.g., `.option(Int)`).
+
+## Example: single field focus
+
+```swift
+struct AddServerView: View {
+  @State private var server = ""
+  @FocusState private var isServerFieldFocused: Bool
+
+  var body: some View {
+    Form {
+      TextField("Server", text: $server)
+        .focused($isServerFieldFocused)
+    }
+    .onAppear { isServerFieldFocused = true }
+  }
+}
+```
+
+## Example: chained focus with enum
+
+```swift
+struct EditTagView: View {
+  enum FocusField { case title, symbol, newTag }
+  @FocusState private var focusedField: FocusField?
+
+  var body: some View {
+    Form {
+      TextField("Title", text: $title)
+        .focused($focusedField, equals: .title)
+        .onSubmit { focusedField = .symbol }
+
+      TextField("Symbol", text: $symbol)
+        .focused($focusedField, equals: .symbol)
+        .onSubmit { focusedField = .newTag }
+    }
+    .onAppear { focusedField = .title }
+  }
+}
+```
+
+## Example: dynamic focus for variable fields
+
+```swift
+struct PollView: View {
+  enum FocusField: Hashable { case option(Int) }
+  @FocusState private var focused: FocusField?
+  @State private var options: [String] = ["", ""]
+  @State private var currentIndex = 0
+
+  var body: some View {
+    ForEach(options.indices, id: \.self) { index in
+      TextField("Option \(index + 1)", text: $options[index])
+        .focused($focused, equals: .option(index))
+        .onSubmit { addOption(at: index) }
+    }
+    .onAppear { focused = .option(0) }
+  }
+
+  private func addOption(at index: Int) {
+    options.append("")
+    currentIndex = index + 1
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.01) {
+      focused = .option(currentIndex)
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep focus state local to the view that owns the fields.
+- Use focus changes to drive UX (validation messages, helper UI).
+- Pair with `.scrollDismissesKeyboard(...)` when using ScrollView/Form.
+
+## Pitfalls
+
+- Don’t store focus state in shared objects; it is view-local.
+- Avoid aggressive focus changes during animation; delay if needed.

package/skills/ios/swiftui-ui-patterns/references/form.md

@@ -0,0 +1,97 @@
+# Form
+
+## Intent
+
+Use `Form` for structured settings, grouped inputs, and action rows. This pattern keeps layout, spacing, and accessibility consistent for data entry screens.
+
+## Core patterns
+
+- Wrap the form in a `NavigationStack` only when it is presented in a sheet or standalone view without an existing navigation context.
+- Group related controls into `Section` blocks.
+- Use `.scrollContentBackground(.hidden)` plus a custom background color when you need design-system colors.
+- Apply `.formStyle(.grouped)` for grouped styling when appropriate.
+- Use `@FocusState` to manage keyboard focus in input-heavy forms.
+
+## Example: settings-style form
+
+```swift
+@MainActor
+struct SettingsView: View {
+  @Environment(Theme.self) private var theme
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        Section("General") {
+          NavigationLink("Display") { DisplaySettingsView() }
+          NavigationLink("Haptics") { HapticsSettingsView() }
+        }
+
+        Section("Account") {
+          Button("Edit profile") { /* open sheet */ }
+            .buttonStyle(.plain)
+        }
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .navigationTitle("Settings")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+    }
+  }
+}
+```
+
+## Example: modal form with validation
+
+```swift
+@MainActor
+struct AddRemoteServerView: View {
+  @Environment(\.dismiss) private var dismiss
+  @Environment(Theme.self) private var theme
+
+  @State private var server: String = ""
+  @State private var isValid = false
+  @FocusState private var isServerFieldFocused: Bool
+
+  var body: some View {
+    NavigationStack {
+      Form {
+        TextField("Server URL", text: $server)
+          .keyboardType(.URL)
+          .textInputAutocapitalization(.never)
+          .autocorrectionDisabled()
+          .focused($isServerFieldFocused)
+          .listRowBackground(theme.primaryBackgroundColor)
+
+        Button("Add") {
+          guard isValid else { return }
+          dismiss()
+        }
+        .disabled(!isValid)
+        .listRowBackground(theme.primaryBackgroundColor)
+      }
+      .formStyle(.grouped)
+      .navigationTitle("Add Server")
+      .navigationBarTitleDisplayMode(.inline)
+      .scrollContentBackground(.hidden)
+      .background(theme.secondaryBackgroundColor)
+      .scrollDismissesKeyboard(.immediately)
+      .toolbar { CancelToolbarItem() }
+      .onAppear { isServerFieldFocused = true }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer `Form` over custom stacks for settings and input screens.
+- Keep rows tappable by using `.contentShape(Rectangle())` and `.buttonStyle(.plain)` on row buttons.
+- Use list row backgrounds to keep section styling consistent with your theme.
+
+## Pitfalls
+
+- Avoid heavy custom layouts inside a `Form`; it can lead to spacing issues.
+- If you need highly custom layouts, prefer `ScrollView` + `VStack`.
+- Don’t mix multiple background strategies; pick either default Form styling or custom colors.

package/skills/ios/swiftui-ui-patterns/references/grids.md

@@ -0,0 +1,71 @@
+# Grids
+
+## Intent
+
+Use `LazyVGrid` for icon pickers, media galleries, and dense visual selections where items align in columns.
+
+## Core patterns
+
+- Use `.adaptive` columns for layouts that should scale across device sizes.
+- Use multiple `.flexible` columns when you want a fixed column count.
+- Keep spacing consistent and small to avoid uneven gutters.
+- Use `GeometryReader` inside grid cells when you need square thumbnails.
+
+## Example: adaptive icon grid
+
+```swift
+let columns = [GridItem(.adaptive(minimum: 120, maximum: 1024))]
+
+LazyVGrid(columns: columns, spacing: 6) {
+  ForEach(icons) { icon in
+    Button {
+      select(icon)
+    } label: {
+      ZStack(alignment: .bottomTrailing) {
+        Image(icon.previewName)
+          .resizable()
+          .aspectRatio(contentMode: .fit)
+          .cornerRadius(6)
+        if icon.isSelected {
+          Image(systemName: "checkmark.seal.fill")
+            .padding(4)
+            .tint(.green)
+        }
+      }
+    }
+    .buttonStyle(.plain)
+  }
+}
+```
+
+## Example: fixed 3-column media grid
+
+```swift
+LazyVGrid(
+  columns: [
+    .init(.flexible(minimum: 100), spacing: 4),
+    .init(.flexible(minimum: 100), spacing: 4),
+    .init(.flexible(minimum: 100), spacing: 4),
+  ],
+  spacing: 4
+) {
+  ForEach(items) { item in
+    GeometryReader { proxy in
+      ThumbnailView(item: item)
+        .frame(width: proxy.size.width, height: proxy.size.width)
+    }
+    .aspectRatio(1, contentMode: .fit)
+  }
+}
+```
+
+## Design choices to keep
+
+- Use `LazyVGrid` for large collections; avoid non-lazy grids for big sets.
+- Keep tap targets full-bleed using `.contentShape(Rectangle())` when needed.
+- Prefer adaptive grids for settings pickers and flexible layouts.
+
+## Pitfalls
+
+- Avoid heavy overlays in every grid cell; it can be expensive.
+- Don’t nest grids inside other grids without a clear reason.

package/skills/ios/swiftui-ui-patterns/references/haptics.md

@@ -0,0 +1,71 @@
+# Haptics
+
+## Intent
+
+Use haptics sparingly to reinforce user actions (tab selection, refresh, success/error) and respect user preferences.
+
+## Core patterns
+
+- Centralize haptic triggers in a `HapticManager` or similar utility.
+- Gate haptics behind user preferences and hardware support.
+- Use distinct types for different UX moments (selection vs. notification vs. refresh).
+
+## Example: simple haptic manager
+
+```swift
+@MainActor
+final class HapticManager {
+  static let shared = HapticManager()
+
+  enum HapticType {
+    case buttonPress
+    case tabSelection
+    case dataRefresh(intensity: CGFloat)
+    case notification(UINotificationFeedbackGenerator.FeedbackType)
+  }
+
+  private let selectionGenerator = UISelectionFeedbackGenerator()
+  private let impactGenerator = UIImpactFeedbackGenerator(style: .heavy)
+  private let notificationGenerator = UINotificationFeedbackGenerator()
+
+  private init() { selectionGenerator.prepare() }
+
+  func fire(_ type: HapticType, isEnabled: Bool) {
+    guard isEnabled else { return }
+    switch type {
+    case .buttonPress:
+      impactGenerator.impactOccurred()
+    case .tabSelection:
+      selectionGenerator.selectionChanged()
+    case let .dataRefresh(intensity):
+      impactGenerator.impactOccurred(intensity: intensity)
+    case let .notification(style):
+      notificationGenerator.notificationOccurred(style)
+    }
+  }
+}
+```
+
+## Example: usage
+
+```swift
+Button("Save") {
+  HapticManager.shared.fire(.notification(.success), isEnabled: preferences.hapticsEnabled)
+}
+
+TabView(selection: $selectedTab) { /* tabs */ }
+  .onChange(of: selectedTab) { _, _ in
+    HapticManager.shared.fire(.tabSelection, isEnabled: preferences.hapticTabSelectionEnabled)
+  }
+```
+
+## Design choices to keep
+
+- Haptics should be subtle and not fire on every tiny interaction.
+- Respect user preferences (toggle to disable).
+- Keep haptic triggers close to the user action, not deep in data layers.
+
+## Pitfalls
+
+- Avoid firing multiple haptics in quick succession.
+- Do not assume haptics are available; check support.

package/skills/ios/swiftui-ui-patterns/references/input-toolbar.md

@@ -0,0 +1,51 @@
+# Input toolbar (bottom anchored)
+
+## Intent
+
+Use a bottom-anchored input bar for chat, composer, or quick actions without fighting the keyboard.
+
+## Core patterns
+
+- Use `.safeAreaInset(edge: .bottom)` to anchor the toolbar above the keyboard.
+- Keep the main content in a `ScrollView` or `List`.
+- Drive focus with `@FocusState` and set initial focus when needed.
+- Avoid embedding the input bar inside the scroll content; keep it separate.
+
+## Example: scroll view + bottom input
+
+```swift
+@MainActor
+struct ConversationView: View {
+  @FocusState private var isInputFocused: Bool
+
+  var body: some View {
+    ScrollViewReader { _ in
+      ScrollView {
+        LazyVStack {
+          ForEach(messages) { message in
+            MessageRow(message: message)
+          }
+        }
+        .padding(.horizontal, .layoutPadding)
+      }
+      .safeAreaInset(edge: .bottom) {
+        InputBar(text: $draft)
+          .focused($isInputFocused)
+      }
+      .scrollDismissesKeyboard(.interactively)
+      .onAppear { isInputFocused = true }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep the input bar visually separated from the scrollable content.
+- Use `.scrollDismissesKeyboard(.interactively)` for chat-like screens.
+- Ensure send actions are reachable via keyboard return or a clear button.
+
+## Pitfalls
+
+- Avoid placing the input view inside the scroll stack; it will jump with content.
+- Avoid nested scroll views that fight for drag gestures.

package/skills/ios/swiftui-ui-patterns/references/lightweight-clients.md

@@ -0,0 +1,93 @@
+# Lightweight Clients (Closure-Based)
+
+Use this pattern to keep networking or service dependencies simple and testable without introducing a full view model or heavy DI framework. It works well for SwiftUI apps where you want a small, composable API surface that can be swapped in previews/tests.
+
+## Intent
+- Provide a tiny "client" type made of async closures.
+- Keep business logic in a store or feature layer, not the view.
+- Enable easy stubbing in previews/tests.
+
+## Minimal shape
+```swift
+struct SomeClient {
+    var fetchItems: (_ limit: Int) async throws -> [Item]
+    var search: (_ query: String, _ limit: Int) async throws -> [Item]
+}
+
+extension SomeClient {
+    static func live(baseURL: URL = URL(string: "https://example.com")!) -> SomeClient {
+        let session = URLSession.shared
+        return SomeClient(
+            fetchItems: { limit in
+                // build URL, call session, decode
+            },
+            search: { query, limit in
+                // build URL, call session, decode
+            }
+        )
+    }
+}
+```
+
+## Usage pattern
+```swift
+@MainActor
+@Observable final class ItemsStore {
+    enum LoadState { case idle, loading, loaded, failed(String) }
+
+    var items: [Item] = []
+    var state: LoadState = .idle
+    private let client: SomeClient
+
+    init(client: SomeClient) {
+        self.client = client
+    }
+
+    func load(limit: Int = 20) async {
+        state = .loading
+        do {
+            items = try await client.fetchItems(limit)
+            state = .loaded
+        } catch {
+            state = .failed(error.localizedDescription)
+        }
+    }
+}
+```
+
+```swift
+struct ContentView: View {
+    @Environment(ItemsStore.self) private var store
+
+    var body: some View {
+        List(store.items) { item in
+            Text(item.title)
+        }
+        .task { await store.load() }
+    }
+}
+```
+
+```swift
+@main
+struct MyApp: App {
+    @State private var store = ItemsStore(client: .live())
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environment(store)
+        }
+    }
+}
+```
+
+## Guidance
+- Keep decoding and URL-building in the client; keep state changes in the store.
+- Make the store accept the client in `init` and keep it private.
+- Avoid global singletons; use `.environment` for store injection.
+- If you need multiple variants (mock/stub), add `static func mock(...)`.
+
+## Pitfalls
+- Don’t put UI state in the client; keep state in the store.
+- Don’t capture `self` or view state in the client closures.

package/skills/ios/swiftui-ui-patterns/references/list.md

@@ -0,0 +1,86 @@
+# List and Section
+
+## Intent
+
+Use `List` for feed-style content and settings-style rows where built-in row reuse, selection, and accessibility matter.
+
+## Core patterns
+
+- Prefer `List` for long, vertically scrolling content with repeated rows.
+- Use `Section` headers to group related rows.
+- Pair with `ScrollViewReader` when you need scroll-to-top or jump-to-id.
+- Use `.listStyle(.plain)` for modern feed layouts.
+- Use `.listStyle(.grouped)` for multi-section discovery/search pages where section grouping helps.
+- Apply `.scrollContentBackground(.hidden)` + a custom background when you need a themed surface.
+- Use `.listRowInsets(...)` and `.listRowSeparator(.hidden)` to tune row spacing and separators.
+- Use `.environment(\\.defaultMinListRowHeight, ...)` to control dense list layouts.
+
+## Example: feed list with scroll-to-top
+
+```swift
+@MainActor
+struct TimelineListView: View {
+  @Environment(\.selectedTabScrollToTop) private var selectedTabScrollToTop
+  @State private var scrollToId: String?
+
+  var body: some View {
+    ScrollViewReader { proxy in
+      List {
+        ForEach(items) { item in
+          TimelineRow(item: item)
+            .id(item.id)
+            .listRowInsets(.init(top: 12, leading: 16, bottom: 6, trailing: 16))
+            .listRowSeparator(.hidden)
+        }
+      }
+      .listStyle(.plain)
+      .environment(\\.defaultMinListRowHeight, 1)
+      .onChange(of: scrollToId) { _, newValue in
+        if let newValue {
+          proxy.scrollTo(newValue, anchor: .top)
+          scrollToId = nil
+        }
+      }
+      .onChange(of: selectedTabScrollToTop) { _, newValue in
+        if newValue == 0 {
+          withAnimation {
+            proxy.scrollTo(ScrollToView.Constants.scrollToTop, anchor: .top)
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: settings-style list
+
+```swift
+@MainActor
+struct SettingsView: View {
+  var body: some View {
+    List {
+      Section("General") {
+        NavigationLink("Display") { DisplaySettingsView() }
+        NavigationLink("Haptics") { HapticsSettingsView() }
+      }
+      Section("Account") {
+        Button("Sign Out", role: .destructive) {}
+      }
+    }
+    .listStyle(.insetGrouped)
+  }
+}
+```
+
+## Design choices to keep
+
+- Use `List` for dynamic feeds, settings, and any UI where row semantics help.
+- Use stable IDs for rows to keep animations and scroll positioning reliable.
+- Prefer `.contentShape(Rectangle())` on rows that should be tappable end-to-end.
+- Use `.refreshable` for pull-to-refresh feeds when the data source supports it.
+
+## Pitfalls
+
+- Avoid heavy custom layouts inside a `List` row; use `ScrollView` + `LazyVStack` instead.
+- Be careful mixing `List` and nested `ScrollView`; it can cause gesture conflicts.

package/skills/ios/swiftui-ui-patterns/references/loading-placeholders.md

@@ -0,0 +1,38 @@
+# Loading & Placeholders
+
+Use this when a view needs a consistent loading state (skeletons, redaction, empty state) without blocking interaction.
+
+## Patterns to prefer
+
+- **Redacted placeholders** for list/detail content to preserve layout while loading.
+- **ContentUnavailableView** for empty or error states after loading completes.
+- **ProgressView** only for short, global operations (use sparingly in content-heavy screens).
+
+## Recommended approach
+
+1. Keep the real layout, render placeholder data, then apply `.redacted(reason: .placeholder)`.
+2. For lists, show a fixed number of placeholder rows (avoid infinite spinners).
+3. Switch to `ContentUnavailableView` when load finishes but data is empty.
+
+## Pitfalls
+
+- Don’t animate layout shifts during redaction; keep frames stable.
+- Avoid nesting multiple spinners; use one loading indicator per section.
+- Keep placeholder count small (3–6) to reduce jank on low-end devices.
+
+## Minimal usage
+
+```swift
+VStack {
+  if isLoading {
+    ForEach(0..<3, id: \.self) { _ in
+      RowView(model: .placeholder())
+    }
+    .redacted(reason: .placeholder)
+  } else if items.isEmpty {
+    ContentUnavailableView("No items", systemImage: "tray")
+  } else {
+    ForEach(items) { item in RowView(model: item) }
+  }
+}
+```