codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/swiftui-ui-patterns/references/sheets.md

@@ -0,0 +1,155 @@
+# Sheets
+
+## Intent
+
+Use a centralized sheet routing pattern so any view can present modals without prop-drilling. This keeps sheet state in one place and scales as the app grows.
+
+## Core architecture
+
+- Define a `SheetDestination` enum that describes every modal and is `Identifiable`.
+- Store the current sheet in a router object (`presentedSheet: SheetDestination?`).
+- Create a view modifier like `withSheetDestinations(...)` that maps the enum to concrete sheet views.
+- Inject the router into the environment so child views can set `presentedSheet` directly.
+
+## Example: item-driven local sheet
+
+Use this when sheet state is local to one screen and does not need centralized routing.
+
+```swift
+@State private var selectedItem: Item?
+
+.sheet(item: $selectedItem) { item in
+  EditItemSheet(item: item)
+}
+```
+
+## Example: SheetDestination enum
+
+```swift
+enum SheetDestination: Identifiable, Hashable {
+  case composer
+  case editProfile
+  case settings
+  case report(itemID: String)
+
+  var id: String {
+    switch self {
+    case .composer, .editProfile:
+      // Use the same id to ensure only one editor-like sheet is active at a time.
+      return "editor"
+    case .settings:
+      return "settings"
+    case .report:
+      return "report"
+    }
+  }
+}
+```
+
+## Example: withSheetDestinations modifier
+
+```swift
+extension View {
+  func withSheetDestinations(
+    sheet: Binding<SheetDestination?>
+  ) -> some View {
+    sheet(item: sheet) { destination in
+      Group {
+        switch destination {
+        case .composer:
+          ComposerView()
+        case .editProfile:
+          EditProfileView()
+        case .settings:
+          SettingsView()
+        case .report(let itemID):
+          ReportView(itemID: itemID)
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: presenting from a child view
+
+```swift
+struct StatusRow: View {
+  @Environment(RouterPath.self) private var router
+
+  var body: some View {
+    Button("Report") {
+      router.presentedSheet = .report(itemID: "123")
+    }
+  }
+}
+```
+
+## Required wiring
+
+For the child view to work, a parent view must:
+- own the router instance,
+- attach `withSheetDestinations(sheet: $router.presentedSheet)` (or an equivalent `sheet(item:)` handler), and
+- inject it with `.environment(router)` after the sheet modifier so the modal content inherits it.
+
+This makes the child assignment to `router.presentedSheet` drive presentation at the root.
+
+## Example: sheets that need their own navigation
+
+Wrap sheet content in a `NavigationStack` so it can push within the modal.
+
+```swift
+struct NavigationSheet<Content: View>: View {
+  var content: () -> Content
+
+  var body: some View {
+    NavigationStack {
+      content()
+        .toolbar { CloseToolbarItem() }
+    }
+  }
+}
+```
+
+## Example: sheet owns its actions
+
+Keep dismissal and confirmation logic inside the sheet when the actions belong to the modal itself.
+
+```swift
+struct EditItemSheet: View {
+  @Environment(\.dismiss) private var dismiss
+  @Environment(Store.self) private var store
+
+  let item: Item
+  @State private var isSaving = false
+
+  var body: some View {
+    VStack {
+      Button(isSaving ? "Saving..." : "Save") {
+        Task { await save() }
+      }
+    }
+  }
+
+  private func save() async {
+    isSaving = true
+    await store.save(item)
+    dismiss()
+  }
+}
+```
+
+## Design choices to keep
+
+- Centralize sheet routing so features can present modals without wiring bindings through many layers.
+- Use `sheet(item:)` to guarantee a single sheet is active and to drive presentation from the enum.
+- Group related sheets under the same `id` when they are mutually exclusive (e.g., editor flows).
+- Keep sheet views lightweight and composed from smaller views; avoid large monoliths.
+- Let sheets own their actions and call `dismiss()` internally instead of forwarding `onCancel` or `onConfirm` closures through many layers.
+
+## Pitfalls
+
+- Avoid mixing `sheet(isPresented:)` and `sheet(item:)` for the same concern; prefer a single enum.
+- Avoid `if let` inside a sheet body when the presentation state already carries the selected model; prefer `sheet(item:)`.
+- Do not store heavy state inside `SheetDestination`; pass lightweight identifiers or models.
+- If multiple sheets can appear from the same screen, give them distinct `id` values.

package/templates/.agent/skills/swiftui-ui-patterns/references/split-views.md

@@ -0,0 +1,72 @@
+# Split views and columns
+
+## Intent
+
+Provide a lightweight, customizable multi-column layout for iPad/macOS without relying on `NavigationSplitView`.
+
+## Custom split column pattern (manual HStack)
+
+Use this when you want full control over column sizing, behavior, and environment tweaks.
+
+```swift
+@MainActor
+struct AppView: View {
+  @Environment(\.horizontalSizeClass) private var horizontalSizeClass
+  @AppStorage("showSecondaryColumn") private var showSecondaryColumn = true
+
+  var body: some View {
+    HStack(spacing: 0) {
+      primaryColumn
+      if shouldShowSecondaryColumn {
+        Divider().edgesIgnoringSafeArea(.all)
+        secondaryColumn
+      }
+    }
+  }
+
+  private var shouldShowSecondaryColumn: Bool {
+    horizontalSizeClass == .regular
+      && showSecondaryColumn
+  }
+
+  private var primaryColumn: some View {
+    TabView { /* tabs */ }
+  }
+
+  private var secondaryColumn: some View {
+    NotificationsTab()
+      .environment(\.isSecondaryColumn, true)
+      .frame(maxWidth: .secondaryColumnWidth)
+  }
+}
+```
+
+## Notes on the custom approach
+
+- Use a shared preference or setting to toggle the secondary column.
+- Inject an environment flag (e.g., `isSecondaryColumn`) so child views can adapt behavior.
+- Prefer a fixed or capped width for the secondary column to avoid layout thrash.
+
+## Alternative: NavigationSplitView
+
+`NavigationSplitView` can handle sidebar + detail + supplementary columns for you, but is harder to customize in cases like:\n- a dedicated notification column independent of selection,\n- custom sizing, or\n- different toolbar behaviors per column.
+
+```swift
+@MainActor
+struct AppView: View {
+  var body: some View {
+    NavigationSplitView {
+      SidebarView()
+    } content: {
+      MainContentView()
+    } detail: {
+      NotificationsView()
+    }
+  }
+}
+```
+
+## When to choose which
+
+- Use the manual HStack split when you need full control or a non-standard secondary column.
+- Use `NavigationSplitView` when you want a standard system layout with minimal customization.

package/templates/.agent/skills/swiftui-ui-patterns/references/tabview.md

@@ -0,0 +1,114 @@
+# TabView
+
+## Intent
+
+Use this pattern for a scalable, multi-platform tab architecture with:
+- a single source of truth for tab identity and content,
+- platform-specific tab sets and sidebar sections,
+- dynamic tabs sourced from data,
+- an interception hook for special tabs (e.g., compose).
+
+## Core architecture
+
+- `AppTab` enum defines identity, labels, icons, and content builder.
+- `SidebarSections` enum groups tabs for sidebar sections.
+- `AppView` owns the `TabView` and selection binding, and routes tab changes through `updateTab`.
+
+## Example: custom binding with side effects
+
+Use this when tab selection needs side effects, like intercepting a special tab to perform an action instead of changing selection.
+
+```swift
+@MainActor
+struct AppView: View {
+  @Binding var selectedTab: AppTab
+
+  var body: some View {
+    TabView(selection: .init(
+      get: { selectedTab },
+      set: { updateTab(with: $0) }
+    )) {
+      ForEach(availableSections) { section in
+        TabSection(section.title) {
+          ForEach(section.tabs) { tab in
+            Tab(value: tab) {
+              tab.makeContentView(
+                homeTimeline: $timeline,
+                selectedTab: $selectedTab,
+                pinnedFilters: $pinnedFilters
+              )
+            } label: {
+              tab.label
+            }
+            .tabPlacement(tab.tabPlacement)
+          }
+        }
+        .tabPlacement(.sidebarOnly)
+      }
+    }
+  }
+
+  private func updateTab(with newTab: AppTab) {
+    if newTab == .post {
+      // Intercept special tabs (compose) instead of changing selection.
+      presentComposer()
+      return
+    }
+    selectedTab = newTab
+  }
+}
+```
+
+## Example: direct binding without side effects
+
+Use this when selection is purely state-driven.
+
+```swift
+@MainActor
+struct AppView: View {
+  @Binding var selectedTab: AppTab
+
+  var body: some View {
+    TabView(selection: $selectedTab) {
+      ForEach(availableSections) { section in
+        TabSection(section.title) {
+          ForEach(section.tabs) { tab in
+            Tab(value: tab) {
+              tab.makeContentView(
+                homeTimeline: $timeline,
+                selectedTab: $selectedTab,
+                pinnedFilters: $pinnedFilters
+              )
+            } label: {
+              tab.label
+            }
+            .tabPlacement(tab.tabPlacement)
+          }
+        }
+        .tabPlacement(.sidebarOnly)
+      }
+    }
+  }
+}
+```
+
+## Design choices to keep
+
+- Centralize tab identity and content in `AppTab` with `makeContentView(...)`.
+- Use `Tab(value:)` with `selection` binding for state-driven tab selection.
+- Route selection changes through `updateTab` to handle special tabs and scroll-to-top behavior.
+- Use `TabSection` + `.tabPlacement(.sidebarOnly)` for sidebar structure.
+- Use `.tabPlacement(.pinned)` in `AppTab.tabPlacement` for a single pinned tab; this is commonly used for iOS 26 `.searchable` tab content, but can be used for any tab.
+
+## Dynamic tabs pattern
+
+- `SidebarSections` handles dynamic data tabs.
+- `AppTab.anyTimelineFilter(filter:)` wraps dynamic tabs in a single enum case.
+- The enum provides label/icon/title for dynamic tabs via the filter type.
+
+## Pitfalls
+
+- Avoid adding ViewModels for tabs; keep state local or in `@Observable` services.
+- Do not nest `@Observable` objects inside other `@Observable` objects.
+- Ensure `AppTab.id` values are stable; dynamic cases should hash on stable IDs.
+- Special tabs (compose) should not change selection.

package/templates/.agent/skills/swiftui-ui-patterns/references/theming.md

@@ -0,0 +1,71 @@
+# Theming and dynamic type
+
+## Intent
+
+Provide a clean, scalable theming approach that keeps view code semantic and consistent.
+
+## Core patterns
+
+- Use a single `Theme` object as the source of truth (colors, fonts, spacing).
+- Inject theme at the app root and read it via `@Environment(Theme.self)` in views.
+- Prefer semantic colors (`primaryBackground`, `secondaryBackground`, `label`, `tint`) instead of raw colors.
+- Keep user-facing theme controls in a dedicated settings screen.
+- Apply Dynamic Type scaling through custom fonts or `.font(.scaled...)`.
+
+## Example: Theme object
+
+```swift
+@MainActor
+@Observable
+final class Theme {
+  var tintColor: Color = .blue
+  var primaryBackground: Color = .white
+  var secondaryBackground: Color = .gray.opacity(0.1)
+  var labelColor: Color = .primary
+  var fontSizeScale: Double = 1.0
+}
+```
+
+## Example: inject at app root
+
+```swift
+@main
+struct MyApp: App {
+  @State private var theme = Theme()
+
+  var body: some Scene {
+    WindowGroup {
+      AppView()
+        .environment(theme)
+    }
+  }
+}
+```
+
+## Example: view usage
+
+```swift
+struct ProfileView: View {
+  @Environment(Theme.self) private var theme
+
+  var body: some View {
+    VStack {
+      Text("Profile")
+        .foregroundStyle(theme.labelColor)
+    }
+    .background(theme.primaryBackground)
+  }
+}
+```
+
+## Design choices to keep
+
+- Keep theme values semantic and minimal; avoid duplicating system colors.
+- Store user-selected theme values in persistent storage if needed.
+- Ensure contrast between text and backgrounds.
+
+## Pitfalls
+
+- Avoid sprinkling raw `Color` values in views; it breaks consistency.
+- Do not tie theme to a single view’s local state.
+- Avoid using `@Environment(\\.colorScheme)` as the only theme control; it should complement your theme.

package/templates/.agent/skills/swiftui-ui-patterns/references/title-menus.md

@@ -0,0 +1,93 @@
+# Title menus
+
+## Intent
+
+Use a title menu in the navigation bar to provide context‑specific filtering or quick actions without adding extra chrome.
+
+## Core patterns
+
+- Use `ToolbarTitleMenu` to attach a menu to the navigation title.
+- Keep the menu content compact and grouped with dividers.
+
+## Example: title menu for filters
+
+```swift
+@ToolbarContentBuilder
+private var toolbarView: some ToolbarContent {
+  ToolbarTitleMenu {
+    Button("Latest") { timeline = .latest }
+    Button("Resume") { timeline = .resume }
+    Divider()
+    Button("Local") { timeline = .local }
+    Button("Federated") { timeline = .federated }
+  }
+}
+```
+
+## Example: attach to a view
+
+```swift
+NavigationStack {
+  TimelineView()
+    .toolbar {
+      toolbarView
+    }
+}
+```
+
+## Example: title + menu together
+
+```swift
+struct TimelineScreen: View {
+  @State private var timeline: TimelineFilter = .home
+
+  var body: some View {
+    NavigationStack {
+      TimelineView()
+        .toolbar {
+          ToolbarItem(placement: .principal) {
+            VStack(spacing: 2) {
+              Text(timeline.title)
+                .font(.headline)
+              Text(timeline.subtitle)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            }
+          }
+
+          ToolbarTitleMenu {
+            Button("Home") { timeline = .home }
+            Button("Local") { timeline = .local }
+            Button("Federated") { timeline = .federated }
+          }
+        }
+        .navigationBarTitleDisplayMode(.inline)
+    }
+  }
+}
+```
+
+## Example: title + subtitle with menu
+
+```swift
+ToolbarItem(placement: .principal) {
+  VStack(spacing: 2) {
+    Text(title)
+      .font(.headline)
+    Text(subtitle)
+      .font(.caption)
+      .foregroundStyle(.secondary)
+  }
+}
+```
+
+## Design choices to keep
+
+- Only show the title menu when filtering or context switching is available.
+- Keep the title readable; avoid long labels that truncate.
+- Use secondary text below the title if extra context is needed.
+
+## Pitfalls
+
+- Don’t overload the menu with too many options.
+- Avoid using title menus for destructive actions.

package/templates/.agent/skills/swiftui-ui-patterns/references/top-bar.md

@@ -0,0 +1,49 @@
+# Top bar overlays (iOS 26+ and fallback)
+
+## Intent
+
+Provide a custom top selector or pill row that sits above scroll content, using `safeAreaBar(.top)` on iOS 26 and a compatible fallback on earlier OS versions.
+
+## iOS 26+ approach
+
+Use `safeAreaBar(edge: .top)` to attach the view to the safe area bar.
+
+```swift
+if #available(iOS 26.0, *) {
+  content
+    .safeAreaBar(edge: .top) {
+      TopSelectorView()
+        .padding(.horizontal, .layoutPadding)
+    }
+}
+```
+
+## Fallback for earlier iOS
+
+Use `.safeAreaInset(edge: .top)` and hide the toolbar background to avoid double layers.
+
+```swift
+content
+  .toolbarBackground(.hidden, for: .navigationBar)
+  .safeAreaInset(edge: .top, spacing: 0) {
+    VStack(spacing: 0) {
+      TopSelectorView()
+        .padding(.vertical, 8)
+        .padding(.horizontal, .layoutPadding)
+        .background(Color.primary.opacity(0.06))
+        .background(Material.ultraThin)
+      Divider()
+    }
+  }
+```
+
+## Design choices to keep
+
+- Use `safeAreaBar` when available; it integrates better with the navigation bar.
+- Use a subtle background + divider in the fallback to keep separation from content.
+- Keep the selector height compact to avoid pushing content too far down.
+
+## Pitfalls
+
+- Don’t stack multiple top insets; it can create extra padding.
+- Avoid heavy, opaque backgrounds that fight the navigation bar.