claudecode-omc 5.6.6 → 5.6.8

package/.local/skills/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/.local/skills/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/.local/skills/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) }
+  }
+}
+```

package/.local/skills/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/.local/skills/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/.local/skills/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/.local/skills/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/.local/skills/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.