buildanything 1.7.0 → 1.8.0

package/skills/ios/swiftui-ui-patterns/references/macos-settings.md

@@ -0,0 +1,71 @@
+# macOS Settings
+
+## Intent
+
+Use this when building a macOS Settings window backed by SwiftUI's `Settings` scene.
+
+## Core patterns
+
+- Declare the Settings scene in the `App` and compile it only for macOS.
+- Keep settings content in a dedicated root view (`SettingsView`) and drive values with `@AppStorage`.
+- Use `TabView` to group settings sections when you have more than one category.
+- Use `Form` inside each tab to keep controls aligned and accessible.
+- Use `OpenSettingsAction` or `SettingsLink` for in-app entry points to the Settings window.
+
+## Example: settings scene
+
+```swift
+@main
+struct MyApp: App {
+  var body: some Scene {
+    WindowGroup {
+      ContentView()
+    }
+    #if os(macOS)
+    Settings {
+      SettingsView()
+    }
+    #endif
+  }
+}
+```
+
+## Example: tabbed settings view
+
+```swift
+@MainActor
+struct SettingsView: View {
+  @AppStorage("showPreviews") private var showPreviews = true
+  @AppStorage("fontSize") private var fontSize = 12.0
+
+  var body: some View {
+    TabView {
+      Form {
+        Toggle("Show Previews", isOn: $showPreviews)
+        Slider(value: $fontSize, in: 9...96) {
+          Text("Font Size (\(fontSize, specifier: "%.0f") pts)")
+        }
+      }
+      .tabItem { Label("General", systemImage: "gear") }
+
+      Form {
+        Toggle("Enable Advanced Mode", isOn: .constant(false))
+      }
+      .tabItem { Label("Advanced", systemImage: "star") }
+    }
+    .scenePadding()
+    .frame(maxWidth: 420, minHeight: 240)
+  }
+}
+```
+
+## Skip navigation
+
+- Avoid wrapping `SettingsView` in a `NavigationStack` unless you truly need deep push navigation.
+- Prefer tabs or sections; Settings is already presented as a separate window and should feel flat.
+- If you must show hierarchical settings, use a single `NavigationSplitView` with a sidebar list of categories.
+
+## Pitfalls
+
+- Don’t reuse iOS-only settings layouts (full-screen stacks, toolbar-heavy flows).
+- Avoid large custom view hierarchies inside `Form`; keep rows focused and accessible.

package/skills/ios/swiftui-ui-patterns/references/matched-transitions.md

@@ -0,0 +1,59 @@
+# Matched transitions
+
+## Intent
+
+Use matched transitions to create smooth continuity between a source view (thumbnail, avatar) and a destination view (sheet, detail, viewer).
+
+## Core patterns
+
+- Use a shared `Namespace` and a stable ID for the source.
+- Use `matchedTransitionSource` + `navigationTransition(.zoom(...))` on iOS 26+.
+- Use `matchedGeometryEffect` for in-place transitions within a view hierarchy.
+- Keep IDs stable across view updates (avoid random UUIDs).
+
+## Example: media preview to full-screen viewer (iOS 26+)
+
+```swift
+struct MediaPreview: View {
+  @Namespace private var namespace
+  @State private var selected: MediaAttachment?
+
+  var body: some View {
+    ThumbnailView()
+      .matchedTransitionSource(id: selected?.id ?? "", in: namespace)
+      .sheet(item: $selected) { item in
+        MediaViewer(item: item)
+          .navigationTransition(.zoom(sourceID: item.id, in: namespace))
+      }
+  }
+}
+```
+
+## Example: matched geometry within a view
+
+```swift
+struct ToggleBadge: View {
+  @Namespace private var space
+  @State private var isOn = false
+
+  var body: some View {
+    Button {
+      withAnimation(.spring) { isOn.toggle() }
+    } label: {
+      Image(systemName: isOn ? "eye" : "eye.slash")
+        .matchedGeometryEffect(id: "icon", in: space)
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer `matchedTransitionSource` for cross-screen transitions.
+- Keep source and destination sizes reasonable to avoid jarring scale changes.
+- Use `withAnimation` for state-driven transitions.
+
+## Pitfalls
+
+- Don’t use unstable IDs; it breaks the transition.
+- Avoid mismatched shapes (e.g., square to circle) unless the design expects it.

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

@@ -0,0 +1,73 @@
+# Media (images, video, viewer)
+
+## Intent
+
+Use consistent patterns for loading images, previewing media, and presenting a full-screen viewer.
+
+## Core patterns
+
+- Use `LazyImage` (or `AsyncImage`) for remote images with loading states.
+- Prefer a lightweight preview component for inline media.
+- Use a shared viewer state (e.g., `QuickLook`) to present a full-screen media viewer.
+- Use `openWindow` for desktop/visionOS and a sheet for iOS.
+
+## Example: inline media preview
+
+```swift
+struct MediaPreviewRow: View {
+  @Environment(QuickLook.self) private var quickLook
+
+  let attachments: [MediaAttachment]
+
+  var body: some View {
+    ScrollView(.horizontal, showsIndicators: false) {
+      HStack {
+        ForEach(attachments) { attachment in
+          LazyImage(url: attachment.previewURL) { state in
+            if let image = state.image {
+              image.resizable().aspectRatio(contentMode: .fill)
+            } else {
+              ProgressView()
+            }
+          }
+          .frame(width: 120, height: 120)
+          .clipped()
+          .onTapGesture {
+            quickLook.prepareFor(
+              selectedMediaAttachment: attachment,
+              mediaAttachments: attachments
+            )
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: global media viewer sheet
+
+```swift
+struct AppRoot: View {
+  @State private var quickLook = QuickLook.shared
+
+  var body: some View {
+    content
+      .environment(quickLook)
+      .sheet(item: $quickLook.selectedMediaAttachment) { selected in
+        MediaUIView(selectedAttachment: selected, attachments: quickLook.mediaAttachments)
+      }
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep previews lightweight; load full media in the viewer.
+- Use shared viewer state so any view can open media without prop-drilling.
+- Use a single entry point for the viewer (sheet/window) to avoid duplicates.
+
+## Pitfalls
+
+- Avoid loading full-size images in list rows; use resized previews.
+- Don’t present multiple viewer sheets at once; keep a single source of truth.

package/skills/ios/swiftui-ui-patterns/references/menu-bar.md

@@ -0,0 +1,101 @@
+# Menu Bar
+
+## Intent
+
+Use this when adding or customizing the macOS/iPadOS menu bar with SwiftUI commands.
+
+## Core patterns
+
+- Add commands at the `Scene` level with `.commands { ... }`.
+- Use `SidebarCommands()` when your UI includes a navigation sidebar.
+- Use `CommandMenu` for app-specific menus and group related actions.
+- Use `CommandGroup` to insert items before/after system groups or replace them.
+- Use `FocusedValue` for context-sensitive menu items that depend on the active scene.
+
+## Example: basic command menu
+
+```swift
+@main
+struct MyApp: App {
+  var body: some Scene {
+    WindowGroup {
+      ContentView()
+    }
+    .commands {
+      CommandMenu("Actions") {
+        Button("Run", action: run)
+          .keyboardShortcut("R")
+        Button("Stop", action: stop)
+          .keyboardShortcut(".")
+      }
+    }
+  }
+
+  private func run() {}
+  private func stop() {}
+}
+```
+
+## Example: insert and replace groups
+
+```swift
+WindowGroup {
+  ContentView()
+}
+.commands {
+  CommandGroup(before: .systemServices) {
+    Button("Check for Updates") { /* open updater */ }
+  }
+
+  CommandGroup(after: .newItem) {
+    Button("New from Clipboard") { /* create item */ }
+  }
+
+  CommandGroup(replacing: .help) {
+    Button("User Manual") { /* open docs */ }
+  }
+}
+```
+
+## Example: focused menu state
+
+```swift
+@Observable
+final class DataModel {
+  var items: [String] = []
+}
+
+struct ContentView: View {
+  @State private var model = DataModel()
+
+  var body: some View {
+    List(model.items, id: \.self) { item in
+      Text(item)
+    }
+    .focusedSceneValue(model)
+  }
+}
+
+struct ItemCommands: Commands {
+  @FocusedValue(DataModel.self) private var model: DataModel?
+
+  var body: some Commands {
+    CommandGroup(after: .newItem) {
+      Button("New Item") {
+        model?.items.append("Untitled")
+      }
+      .disabled(model == nil)
+    }
+  }
+}
+```
+
+## Menu bar and Settings
+
+- Defining a `Settings` scene adds the Settings menu item on macOS automatically.
+- If you need a custom entry point inside the app, use `OpenSettingsAction` or `SettingsLink`.
+
+## Pitfalls
+
+- Avoid registering the same keyboard shortcut in multiple command groups.
+- Don’t use menu items as the only discoverable entry point for critical features.

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

@@ -0,0 +1,159 @@
+# NavigationStack
+
+## Intent
+
+Use this pattern for programmatic navigation and deep links, especially when each tab needs an independent navigation history. The key idea is one `NavigationStack` per tab, each with its own path binding and router object.
+
+## Core architecture
+
+- Define a route enum that is `Hashable` and represents all destinations.
+- Create a lightweight router (or use a library such as `https://github.com/Dimillian/AppRouter`) that owns the `path` and any sheet state.
+- Each tab owns its own router instance and binds `NavigationStack(path:)` to it.
+- Inject the router into the environment so child views can navigate programmatically.
+- Centralize destination mapping with a single `navigationDestination(for:)` block (or a `withAppRouter()` modifier).
+
+## Example: custom router with per-tab stack
+
+```swift
+@MainActor
+@Observable
+final class RouterPath {
+  var path: [Route] = []
+  var presentedSheet: SheetDestination?
+
+  func navigate(to route: Route) {
+    path.append(route)
+  }
+
+  func reset() {
+    path = []
+  }
+}
+
+enum Route: Hashable {
+  case account(id: String)
+  case status(id: String)
+}
+
+@MainActor
+struct TimelineTab: View {
+  @State private var routerPath = RouterPath()
+
+  var body: some View {
+    NavigationStack(path: $routerPath.path) {
+      TimelineView()
+        .navigationDestination(for: Route.self) { route in
+          switch route {
+          case .account(let id): AccountView(id: id)
+          case .status(let id): StatusView(id: id)
+          }
+        }
+    }
+    .environment(routerPath)
+  }
+}
+```
+
+## Example: centralized destination mapping
+
+Use a shared view modifier to avoid duplicating route switches across screens.
+
+```swift
+extension View {
+  func withAppRouter() -> some View {
+    navigationDestination(for: Route.self) { route in
+      switch route {
+      case .account(let id):
+        AccountView(id: id)
+      case .status(let id):
+        StatusView(id: id)
+      }
+    }
+  }
+}
+```
+
+Then apply it once per stack:
+
+```swift
+NavigationStack(path: $routerPath.path) {
+  TimelineView()
+    .withAppRouter()
+}
+```
+
+## Example: binding per tab (tabs with independent history)
+
+```swift
+@MainActor
+struct TabsView: View {
+  @State private var timelineRouter = RouterPath()
+  @State private var notificationsRouter = RouterPath()
+
+  var body: some View {
+    TabView {
+      TimelineTab(router: timelineRouter)
+      NotificationsTab(router: notificationsRouter)
+    }
+  }
+}
+```
+
+## Example: generic tabs with per-tab NavigationStack
+
+Use this when tabs are built from data and each needs its own path without hard-coded names.
+
+```swift
+@MainActor
+struct TabsView: View {
+  @State private var selectedTab: AppTab = .timeline
+  @State private var tabRouter = TabRouter()
+
+  var body: some View {
+    TabView(selection: $selectedTab) {
+      ForEach(AppTab.allCases) { tab in
+        NavigationStack(path: tabRouter.binding(for: tab)) {
+          tab.makeContentView()
+        }
+        .environment(tabRouter.router(for: tab))
+        .tabItem { tab.label }
+        .tag(tab)
+      }
+    }
+  }
+}
+```
+
+@MainActor
+@Observable
+final class TabRouter {
+  private var routers: [AppTab: RouterPath] = [:]
+
+  func router(for tab: AppTab) -> RouterPath {
+    if let router = routers[tab] { return router }
+    let router = RouterPath()
+    routers[tab] = router
+    return router
+  }
+
+  func binding(for tab: AppTab) -> Binding<[Route]> {
+    let router = router(for: tab)
+    return Binding(get: { router.path }, set: { router.path = $0 })
+  }
+}
+
+## Design choices to keep
+
+- One `NavigationStack` per tab to preserve independent history.
+- A single source of truth for navigation state (`RouterPath` or library router).
+- Use `navigationDestination(for:)` to map routes to views.
+- Reset the path when app context changes (account switch, logout, etc.).
+- Inject the router into the environment so child views can navigate and present sheets without prop-drilling.
+- Keep sheet presentation state on the router if you want a single place to manage modals.
+
+## Pitfalls
+
+- Do not share one path across all tabs unless you want global history.
+- Ensure route identifiers are stable and `Hashable`.
+- Avoid storing view instances in the path; store lightweight route data instead.
+- If using a router object, keep it outside other `@Observable` objects to avoid nested observation.

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

@@ -0,0 +1,45 @@
+# Overlay and toasts
+
+## Intent
+
+Use overlays for transient UI (toasts, banners, loaders) without affecting layout.
+
+## Core patterns
+
+- Use `.overlay(alignment:)` to place global UI without changing the underlying layout.
+- Keep overlays lightweight and dismissible.
+- Use a dedicated `ToastCenter` (or similar) for global state if multiple features trigger toasts.
+
+## Example: toast overlay
+
+```swift
+struct AppRootView: View {
+  @State private var toast: Toast?
+
+  var body: some View {
+    content
+      .overlay(alignment: .top) {
+        if let toast {
+          ToastView(toast: toast)
+            .transition(.move(edge: .top).combined(with: .opacity))
+            .onAppear {
+              DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
+                withAnimation { self.toast = nil }
+              }
+            }
+        }
+      }
+  }
+}
+```
+
+## Design choices to keep
+
+- Prefer overlays for transient UI rather than embedding in layout stacks.
+- Use transitions and short auto-dismiss timers.
+- Keep the overlay aligned to a clear edge (`.top` or `.bottom`).
+
+## Pitfalls
+
+- Avoid overlays that block all interaction unless explicitly needed.
+- Don’t stack many overlays; use a queue or replace the current toast.

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

@@ -0,0 +1,62 @@
+# Performance guardrails
+
+## Intent
+
+Use these rules when a SwiftUI screen is large, scroll-heavy, frequently updated, or at risk of unnecessary recomputation.
+
+## Core rules
+
+- Give `ForEach` and list content stable identity. Do not use unstable indices as identity when the collection can reorder or mutate.
+- Keep expensive filtering, sorting, and formatting out of `body`; precompute or move it into a model/helper when it is not trivial.
+- Narrow observation scope so only the views that read changing state need to update.
+- Prefer lazy containers for larger scrolling content and extract subviews when only part of a screen changes frequently.
+- Avoid swapping entire top-level view trees for small state changes; keep a stable root view and vary localized sections or modifiers.
+
+## Example: stable identity
+
+```swift
+ForEach(items) { item in
+  Row(item: item)
+}
+```
+
+Prefer that over index-based identity when the collection can change order:
+
+```swift
+ForEach(Array(items.enumerated()), id: \.offset) { _, item in
+  Row(item: item)
+}
+```
+
+## Example: move expensive work out of body
+
+```swift
+struct FeedView: View {
+  let items: [FeedItem]
+
+  private var sortedItems: [FeedItem] {
+    items.sorted(using: KeyPathComparator(\.createdAt, order: .reverse))
+  }
+
+  var body: some View {
+    List(sortedItems) { item in
+      FeedRow(item: item)
+    }
+  }
+}
+```
+
+If the work is more expensive than a small derived property, move it into a model, store, or helper that updates less often.
+
+## When to investigate further
+
+- Janky scrolling in long feeds or grids
+- Typing lag from search or form validation
+- Overly broad view updates when one small piece of state changes
+- Large screens with many conditionals or repeated formatting work
+
+## Pitfalls
+
+- Recomputing heavy transforms every render
+- Observing a large object from many descendants when only one field matters
+- Building custom scroll containers when `List`, `LazyVStack`, or `LazyHGrid` would already solve the problem

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

@@ -0,0 +1,48 @@
+# Previews
+
+## Intent
+
+Use previews to validate layout, state wiring, and injected dependencies without relying on a running app or live services.
+
+## Core rules
+
+- Add `#Preview` coverage for the primary state plus important secondary states such as loading, empty, and error.
+- Use deterministic fixtures, mocks, and sample data. Do not make previews depend on live network calls, real databases, or global singletons.
+- Install required environment dependencies directly in the preview so the view can render in isolation.
+- Keep preview setup close to the view until it becomes noisy; then extract lightweight preview helpers or fixtures.
+- If a preview crashes, fix the state initialization or dependency wiring before expanding the feature further.
+
+## Example: simple preview states
+
+```swift
+#Preview("Loaded") {
+  ProfileView(profile: .fixture)
+}
+
+#Preview("Empty") {
+  ProfileView(profile: nil)
+}
+```
+
+## Example: preview with injected dependencies
+
+```swift
+#Preview("Search results") {
+  SearchView()
+    .environment(SearchClient.preview(results: [.fixture, .fixture2]))
+    .environment(Theme.preview)
+}
+```
+
+## Preview checklist
+
+- Does the preview install every required environment dependency?
+- Does it cover at least one success path and one non-happy path?
+- Are fixtures stable and small enough to be read quickly?
+- Can the preview render without network, auth, or app-global initialization?
+
+## Pitfalls
+
+- Do not hide preview crashes by making dependencies optional if the production view requires them.
+- Avoid huge inline fixtures when a named sample is easier to read.
+- Do not couple previews to global shared singletons unless the project has no alternative.