MSRCH-5448: Document numeric facet StatsBucket + RangeBucket

src/pages/graphql/schema/live-search/queries/product-search.md

@@ -18,7 +18,7 @@ See [Boundaries and Limits](https://experienceleague.adobe.com/en/docs/commerce/
 ```graphql
 productSearch(
     phrase: String!
-    context: QueryContextInput!
+    context: QueryContextInput
     current_page: Int = 1
     page_size: Int = 20
     sort: [ProductSearchSortInput!]
@@ -457,11 +457,11 @@ filter: [
     in: ["Catalog", "Catalog, Search"]
   },
   {
-    attribute:"categoryPath",
-    eq: ["women/bottoms-women"]
+    attribute: "categoryPath",
+    eq: "women/bottoms-women"
   },
   {
-    attribute:"categories",
+    attribute: "categories",
     in: ["women/bottoms-women/pants-women"]
   }
 ]
@@ -481,7 +481,15 @@ Dynamic facets appear only when relevant, and the selection changes according to
 
 Intelligent dynamic facets measure the frequency that an attribute appears in the results list and its prevalence throughout the catalog. Live Search uses this information to determine the order of returned products. This makes it possible to return two types of dynamic facets: Those that are most significant, followed by those that are most popular.
 
-The `buckets` subobject divides the data into manageable groups. For the `price` and similar numeric attributes, each bucket defines a price range and counts the items within that price range. Meanwhile, the buckets associated with the `categories` attribute list details about each category a product is a member of. The contents of dynamic facet buckets vary.
+The `buckets` array divides the data into manageable groups. For the `price` and similar numeric attributes, each bucket defines a price range and counts the items within that price range. The buckets associated with the `categories` attribute list details about each category a product is a member of. The contents of dynamic facet buckets vary.
+
+The `buckets` array is polymorphic. Use `__typename` or a type-specific fragment, such as `... on RangeBucket` or `... on StatsBucket`, to identify which [bucket implementation](#bucket-data-type) was returned for each entry.
+
+For numeric attributes, such as `price` or a rating attribute, `buckets` can contain both a `RangeBucket` and a `StatsBucket`. The `RangeBucket.from` and `RangeBucket.to` values can reflect the facet's configured bounds or slider bounds rather than the minimum and maximum values actually present in the filtered results.
+
+<InlineAlert variant="info" slots="text"/>
+
+When a `StatsBucket` is returned alongside a `RangeBucket` for the same facet, use `StatsBucket.min` and `StatsBucket.max` to determine the actual minimum and maximum values of the filtered result set. Do not infer these values from `RangeBucket.from` and `RangeBucket.to` alone.
 
 The following snippet returns all information about the applicable facets for a search:
 
@@ -1010,7 +1018,7 @@ Implement `StatsBucket` to retrieve statistics across multiple buckets.
 | --- | --- | --- |
 | `max` | Float! | The maximum value |
 | `min` | Float! | The minimum value |
-| `title` | String! | The display text defining the bucket |
+| `title` | String! | The display text defining the bucket. This value can be an empty string. |
 
 #### ProductSearchItem data type