Feat: Updating Product Service with new Methods, DTOs for ListingResult And Slider Bounds

docs/product-listing.md

@@ -1,8 +1,9 @@
 # Product Listing
 
 `Modules\Core\Catalog\Services\ProductService` provides catalog browsing/filtering AND single-product
-lookup for a storefront — `list()`, `getById()`, `getBySlug()` — all reading directly from the
-Meilisearch index rather than the database. One data source for everything this service does.
+lookup for a storefront — `list()`, `getById()`, `getBySlug()`, `random()`, `variantSummaries()` —
+all reading directly from the Meilisearch index rather than the database. One data source for
+everything this service does.
 
 This is separate from `Modules\Core\Catalog\Services\ProductSearchService` (see `product-search.md`), which
 handles free-text query search. `ProductService` is for browsing/lookup without a search term.
@@ -28,13 +29,14 @@ use Modules\Core\Catalog\Enums\ProductSort;
 
 $service = app(ProductService::class);
 
-// List everything, paginated — returns a real Illuminate\Pagination\LengthAwarePaginator,
-// built from the localized Meilisearch hits (not Scout's own paginateRaw() result — see
-// "Meilisearch driver quirk" below), so it behaves like any other Laravel paginator.
-$products = $service->list(perPage: 24, page: 1);
+// One call for everything a listing page needs — products AND the price slider's
+// bounds together, as a Modules\Core\Catalog\DTOs\ProductListingResult. A caller
+// used to have to call list() and priceSliderBounds() (or the older priceRange())
+// separately and glue the results together itself; that's now list()'s own job.
+$listing = $service->list(perPage: 24, page: 1);
 
 // Filter by collection, brand, price range, and/or stock
-$products = $service->list(
+$listing = $service->list(
     filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0, inStockOnly: true),
     perPage: 24,
     page: 1,
@@ -42,8 +44,13 @@ $products = $service->list(
 
 // Sort — cheapest/priciest first, or newest first. Omit for Meilisearch's default
 // relevance ordering (irrelevant here since the query is always empty).
-$products = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
+$listing = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
 
+$products = $listing->products;  // a real Illuminate\Pagination\LengthAwarePaginator,
+                                  // built from the localized Meilisearch hits (not Scout's
+                                  // own paginateRaw() result — see "Meilisearch driver
+                                  // quirk" below), so it behaves like any other Laravel
+                                  // paginator.
 $products->items();            // array of Meilisearch documents (plain arrays, not models)
 $products->total();
 $products->perPage();
@@ -51,12 +58,32 @@ $products->currentPage();
 $products->lastPage();
 $products->links();            // in a Blade view — renders pagination links as usual
 
+$bounds = $listing->priceBounds;  // Modules\Core\Catalog\DTOs\PriceSliderBounds
+$bounds->floor;    // ?int — floor() of the matching range's minimum, in whole currency units
+$bounds->ceil;     // ?int — ceil() of the matching range's maximum
+$bounds->filtered; // bool — whether the applied filters' minPrice/maxPrice actually
+                   // narrow the slider below/above these bounds (drives whether a
+                   // "clear filter" control should show)
+
 // Single product, by primary key
 $product = $service->getById(367);   // array, or null if not found
 
 // Single product, by URL slug (any locale — slugs are indexed across all languages)
 $product = $service->getBySlug('erotika-mprelok');   // array, or null if not found
 
+// $limit random products — still scoped to the index's own default channel/status
+// visibility, unlike Eloquent's Product::inRandomOrder() (which has no notion of
+// that filtering at all). Meilisearch has no ORDER BY RANDOM() equivalent, so this
+// pulls every matching id only, shuffles in PHP, then fetches the full localized
+// documents for just the ids picked — see random()'s own docblock.
+$randomProducts = $service->random(13);   // array of documents, same shape as list()'s items
+
+// The id/price/image of every variant on a product document — the base price and
+// thumbnail a variant picker/swatch list needs, without reaching into
+// $product['variants'][n]['prices'][0]/['media'][0] yourself.
+$variants = $service->variantSummaries($product);
+// [['id' => 1204, 'price' => 19.99, 'image' => 'https://.../thumb.jpg'], ...]
+
 // Facet counts for a sidebar — value => matching product count, scoped to whatever
 // $filters is passed. Does NOT exclude the faceted field itself from $filters — see
 // facets()'s docblock for why, and how to build a standard "every option's count,
@@ -64,11 +91,13 @@ $product = $service->getBySlug('erotika-mprelok');   // array, or null if not fo
 $brandCounts = $service->facets('brand', filters: new ProductFilters(collectionId: 17));
 // ['3Dealer.gr - 3D printed creations' => 48, 'Kraniou Topos - 3D printed creations' => 135]
 
-// Min/max price across matching products, for sizing a price-range slider.
-// minPrice/maxPrice are ALWAYS excluded from the filter driving this (unlike
-// facets(), which doesn't auto-exclude) — the slider's own bounds shouldn't shrink
-// to whatever range is currently selected on it. Other filters (collectionId,
-// brand, inStockOnly) still apply normally.
+// Min/max price across matching products — the raw, unrounded values list() itself
+// uses to build priceBounds above. minPrice/maxPrice are ALWAYS excluded from the
+// filter driving this (unlike facets(), which doesn't auto-exclude) — the slider's
+// own bounds shouldn't shrink to whatever range is currently selected on it. Other
+// filters (collectionId, brand, inStockOnly) still apply normally. Pass $query too
+// to scope the range to a text search's own matches (see product-search.md) rather
+// than the whole catalog.
 $range = $service->priceRange(new ProductFilters(collectionId: 17));
 // ['min' => 0.0, 'max' => 120.0]
 ```
@@ -77,8 +106,8 @@ All `ProductFilters` fields are optional; only the ones set are added to the Mei
 
 `facets()` only makes sense on discrete-value filterable fields (`brand`, `in_stock`) — a numeric
 field like `price` would return one "facet" per exact price, not a usable range bucket. Use
-`priceRange()` for `price` instead, which reads Meilisearch's `facetStats` (min/max), a different
-feature from `facetDistribution`.
+`priceRange()` (or `list()`'s own `priceBounds`) for `price` instead, which reads Meilisearch's
+`facetStats` (min/max), a different feature from `facetDistribution`.
 
 ---