feat(snapshots): Add snapshot group sidecar override (#271)

* feat(snapshots): Add snapshotGroup modifier to override sidecar group

Introduce a `.snapshotGroup(...)` view modifier that lets authors override the
top-level `group` field in the exported JSON sidecar. Accepts a custom string or
a `SnapshotGroup` strategy: `.default` keeps the generated group, `.custom` uses
a provided name, and `.module` groups by the preview container's module name.

Previously the sidecar `group` was always derived from the preview name, file
path, and module with no way to influence it. The override is plumbed from the
preference key through the rendering strategies and resolved during export, with
empty or whitespace-only custom values falling back to the generated group.
Exported filenames and manifest output are unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(snapshots): Apply snapshotGroup modifier to demo previews

Exercise the new snapshotGroup modifier across the DemoModule card
previews by grouping them under "Card Views" and overriding OSVersionView
to the module group. Remove the unused snapshotDiffThreshold override from
RideShareButton now that grouping covers the demo coverage.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Cameron Cooke

Examples/DemoApp/DemoApp/TestViews/OSVersionView.swift

@@ -7,6 +7,7 @@
 
 import Foundation
 import SwiftUI
+import SnapshotPreferences
 
 struct OSVersionView: View {
     var body: some View {
@@ -35,5 +36,6 @@ struct OSVersionView: View {
 struct OSVersionView_Previews: PreviewProvider {
     static var previews: some View {
         OSVersionView()
+        .snapshotGroup(.module)
     }
 }

Examples/DemoApp/DemoApp/TestViews/RideShareButton.swift

@@ -34,8 +34,6 @@ struct RideShareButtonView_Previews: PreviewProvider {
         .previewLayout(.sizeThatFits)
         .padding()
         .previewDisplayName("Ride Share Button View - Light")
-        // This should never show as a diff
-        .snapshotDiffThreshold(1.0)
       #if os(iOS)
         .snapshotRenderingMode(.coreAnimation)
       #endif

Examples/DemoApp/DemoModule/FeatureCardView.swift

@@ -6,6 +6,7 @@
 //
 
 import SwiftUI
+import SnapshotPreferences
 
 struct FeatureCardView: View {
     var imageName: String
@@ -45,5 +46,6 @@ struct FeatureCardView_Previews: PreviewProvider {
                         description: "This is a description of the feature and its benefits.")
             .previewLayout(.sizeThatFits)
             .padding()
+            .snapshotGroup("Card Views")
     }
 }

Examples/DemoApp/DemoModule/InfoCardView.swift

@@ -6,6 +6,7 @@
 //
 
 import SwiftUI
+import SnapshotPreferences
 
 struct InfoCardView: View {
     var title: String
@@ -49,5 +50,6 @@ struct InfoCardView_Previews: PreviewProvider {
                 .previewLayout(.sizeThatFits)
                 .padding()
         }
+        .snapshotGroup("Card Views")
     }
 }

Examples/DemoApp/DemoModule/ProductCard.swift

@@ -6,6 +6,7 @@
 //
 
 import SwiftUI
+import SnapshotPreferences
 
 struct ProductCardView: View {
     var imageName: String
@@ -45,5 +46,6 @@ struct ProductCardView_Previews: PreviewProvider {
             ProductCardView(imageName: "product-image", productName: "Sample Product 2", price: 49.99)
             .previewLayout(.sizeThatFits)
         }
+        .snapshotGroup("Card Views")
     }
 }

Examples/DemoApp/DemoModule/TripCardView.swift

@@ -6,6 +6,7 @@
 //
 
 import SwiftUI
+import SnapshotPreferences
 
 struct TripCardView: View {
     var destination: String
@@ -51,5 +52,6 @@ struct TripCardView_Previews: PreviewProvider {
                      imageName: "product-image")
             .previewLayout(.device)
             .padding()
+            .snapshotGroup("Card Views")
     }
 }

README.md

@@ -149,7 +149,7 @@ Each `.json` sidecar contains the following fields:
 | Field | Description |
 | --- | --- |
 | `display_name` | Snapshot name shown in Sentry. Generated from the preview name, file path, and module so exported filenames stay stable and unambiguous. |
-| `group` | Grouping key Sentry uses to organize related snapshots. Generated from the preview name, file path, and module. |
+| `group` | Grouping key Sentry uses to organize related snapshots. Generated from the preview name, file path, and module by default. |
 | `diff_threshold` | Allowed visual difference for this snapshot. See details below. |
 | `tags` | Optional key-value pairs used to filter and group snapshots in Sentry. |
 | `context` | Supporting metadata such as test name, simulator info, orientation, color scheme, source line, preview attributes, and any custom context you add. These fields are surfaced on the snapshot detail page in Sentry's UI. |
@@ -158,6 +158,8 @@ SnapshotPreviews adds these `context` keys by default when values are available:
 
 Use `.snapshotAdditionalContext(...)` to add custom fields to `context`. Custom context is shallow-merged into the generated context, so a custom key such as `"test_name"` replaces the generated value. Supported custom values are strings, numbers, booleans, and nested objects.
 
+Use `.snapshotGroup(...)` to override the default `group` behaviour in the Sentry Snapshots UI. Pass a custom string such as `.snapshotGroup("Checkout")`, or a strategy: `.snapshotGroup(.module)` which groups by the preview container's module name.
+
 Use the `.snapshotDiffThreshold(...)` view modifier from the `SnapshotPreferences` product to customize the allowed visual difference for a specific preview. For example, `.snapshotDiffThreshold(0.05)` allows up to a 5% difference for that snapshot.
 
 ```swift
@@ -167,6 +169,7 @@ import SnapshotPreferences
   MapPreview()
     .snapshotTags(["screen": "map"])
     .snapshotAdditionalContext(["fixture": "city-route"])
+    .snapshotGroup("Navigation")
     .snapshotDiffThreshold(0.05)
 }
 ```
@@ -218,6 +221,7 @@ Link the `SnapshotPreferences` product to your app target to customize individua
 | `.snapshotExpansion(false)` | You want to preserve the visible scroll viewport instead of capturing all scroll content. | By default, scroll views are expanded so the snapshot includes their full content. Setting this to `false` keeps the scroll view at its normal visible height. |
 | `.snapshotTags(["area": "checkout"])` | You want searchable labels on the exported snapshot. | Adds top-level `tags` to the JSON sidecar. Repeated tag modifiers merge, and later duplicate keys win. |
 | `.snapshotAdditionalContext(["fixture": "loaded"])` | You want extra sidecar metadata for debugging or filtering. | Adds fields to the JSON sidecar `context` object. Repeated context modifiers merge, and later duplicate keys win. Custom keys override generated context keys. |
+| `.snapshotGroup("Checkout")` | You want to control how related snapshots are grouped in Sentry. | Overrides the top-level `group` in the JSON sidecar. Also accepts `.snapshotGroup(.module)` to group by the preview container's module name, and `.snapshotGroup(.default)` to keep the generated group. Empty or whitespace-only custom strings fall back to the generated group. Does not change exported filenames or all-image-names manifest output. |
 | `.snapshotDiffThreshold(0.05)` | A snapshot has small expected pixel differences. | Sets `diff_threshold` in the exported sidecar for this preview. `0.05` allows up to a 5% changed-pixel share before Sentry marks the image as changed. |
 
 ### Variants

Sources/SnapshotPreferences/EmergeModifierFinder.swift

@@ -27,6 +27,7 @@ class EmergeModifierState: NSObject {
     appStoreSnapshot = nil
     tags = [:]
     additionalContext = [:]
+    groupOverride = nil
   }
 
   var expansionPreference: Bool?
@@ -36,6 +37,7 @@ class EmergeModifierState: NSObject {
   var appStoreSnapshot: Bool?
   var tags: [String: String] = [:]
   var additionalContext: [String: SnapshotMetadataValue] = [:]
+  var groupOverride: SnapshotGroup?
 }
 
 @objc(EmergeModifierFinder)
@@ -64,5 +66,8 @@ class EmergeModifierFinder: NSObject {
       .onPreferenceChange(SnapshotAdditionalContextPreferenceKey.self, perform: { value in
         EmergeModifierState.shared.additionalContext = value
       })
+      .onPreferenceChange(SnapshotGroupPreferenceKey.self, perform: { value in
+        EmergeModifierState.shared.groupOverride = value
+      })
   }
 }

Sources/SnapshotPreferences/SnapshotMetadataPreference.swift

@@ -14,6 +14,14 @@ struct SnapshotTagsPreferenceKey: PreferenceKey {
   }
 }
 
+struct SnapshotGroupPreferenceKey: PreferenceKey {
+  static var defaultValue: SnapshotGroup? = nil
+
+  static func reduce(value: inout SnapshotGroup?, nextValue: () -> SnapshotGroup?) {
+    value = nextValue() ?? value
+  }
+}
+
 struct SnapshotAdditionalContextPreferenceKey: PreferenceKey {
   static var defaultValue: [String: SnapshotMetadataValue] = [:]
 
@@ -45,4 +53,22 @@ extension View {
       value: SnapshotMetadataValue.dictionary(from: context)
     )
   }
+
+  /// Overrides the top-level `group` field in the exported snapshot sidecar.
+  ///
+  /// If the same group modifier is set more than once, the later modifier value is used.
+  /// This changes only JSON sidecar metadata — exported PNG/JSON filenames are unaffected.
+  public func snapshotGroup(_ group: String) -> some View {
+    snapshotGroup(.custom(group))
+  }
+
+  /// Overrides the top-level `group` field in the exported snapshot sidecar using a strategy.
+  ///
+  /// `.default` keeps the generated group, `.custom` uses the provided name, and `.module`
+  /// groups by the preview container's module name. If the same group modifier is set more
+  /// than once, the later modifier value is used. This changes only JSON sidecar metadata —
+  /// exported PNG/JSON filenames are unaffected.
+  public func snapshotGroup(_ group: SnapshotGroup) -> some View {
+    preference(key: SnapshotGroupPreferenceKey.self, value: group)
+  }
 }

Sources/SnapshotPreviewsCore/AppKitRenderingStrategy.swift

@@ -47,7 +47,7 @@ public class AppKitRenderingStrategy: RenderingStrategy {
     window.contentViewController = NSViewController()
     window.setContentSize(AppKitContainer.defaultSize)
     window.contentViewController = vc
-    vc.rendered = { [weak window, weak vc] mode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext in
+    vc.rendered = { [weak window, weak vc] mode, precision, accessibilityEnabled, appStoreSnapshot, tags, additionalContext, groupOverride in
       DispatchQueue.main.async {
         Self.takeSnapshot(mode: mode ?? .nsView, viewController: vc, window: window) { image in
           completion(
@@ -58,7 +58,8 @@ public class AppKitRenderingStrategy: RenderingStrategy {
               colorScheme: _colorScheme,
               appStoreSnapshot: appStoreSnapshot,
               tags: tags,
-              additionalContext: additionalContext))
+              additionalContext: additionalContext,
+              groupOverride: groupOverride))
         }
       }
     }
@@ -118,7 +119,7 @@ final class AppKitContainer: NSHostingController<EmergeModifierView>, ScrollExpa
   var heightAnchor: NSLayoutConstraint?
   var previousHeight: CGFloat?
 
-  public var rendered: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue]) -> Void)? {
+  public var rendered: ((EmergeRenderingMode?, Float?, Bool?, Bool?, [String: String], [String: SnapshotMetadataValue], SnapshotGroup?) -> Void)? {
     didSet { didCall = false }
   }
 
@@ -168,7 +169,7 @@ final class AppKitContainer: NSHostingController<EmergeModifierView>, ScrollExpa
     guard !didCall else { return }
 
     didCall = true
-    rendered?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext)
+    rendered?(rootView.emergeRenderingMode, rootView.precision, rootView.accessibilityEnabled, rootView.appStoreSnapshot, rootView.tags, rootView.additionalContext, rootView.groupOverride)
   }
 
   override func updateViewConstraints() {