refactor(composables): product listing

.changeset/better-views-sin.md

@@ -0,0 +1,185 @@
+---
+"@shopware/composables": minor
+---
+
+Refactor product listing composables into modular, context-based architecture with improved SSR support.
+
+## Breaking Changes
+
+### 1. Pagination Parameter Change
+
+**Changed:** The pagination parameter has been standardized from `page` to `p`:
+
+```typescript
+// Before
+changeCurrentPage(2);  // Sends: { body: { page: 2 } }
+
+// After
+changeCurrentPage(2);  // Sends: { body: { p: 2 } }
+```
+
+**Impact:** If you're directly using the API client or inspecting search parameters, update to use `p` instead of `page`.
+
+### 2. Error Handling - Context Required
+
+**Changed:** `useCategoryListing()` now **throws an error** if called without context:
+
+```typescript
+// Before - Would fail silently or return null
+const listing = useCategoryListing();
+
+// After - Throws clear error
+const listing = useCategoryListing();
+// Error: "[useCategoryListing] Please call `createCategoryListingContext`
+// on the appropriate parent component"
+```
+
+**Impact:** You **must** call `createCategoryListingContext(initialListing)` before using `useCategoryListing()`.
+
+### 3. Loading State Split
+
+**Changed:** Loading states are now separated:
+
+```typescript
+// Before - Single loading ref
+const { loading } = useListing();
+
+// After - Two separate refs
+const { loading, loadingMore } = useListing();
+// loading - for search operations
+// loadingMore - for pagination/load more operations
+```
+
+**Impact:** If you're checking loading state for pagination, also check `loadingMore`.
+
+### 4. Context-Based Architecture (Required for Category Pages)
+
+**New Requirement:** Category pages must create listing context in parent component:
+
+```ts
+// Required in CmsPage.vue or similar
+import { createCategoryListingContext } from "@shopware/composables";
+
+const initialListing = getProductListingFromCmsPage(props.content);
+if (initialListing) {
+  createCategoryListingContext(initialListing);
+}
+```
+
+**Impact:** Without this, child components using `useCategoryListing()` will throw errors.
+
+### 5. Composable Structure (Internal Change)
+
+The `useListing` composable has been refactored into smaller, focused composables:
+
+- `useListingCore` - Core listing state management
+- `useProductListingFilters` - Filter state and operations
+- `useProductListingPagination` - Pagination logic
+- `useProductListingProducts` - Product data handling
+- `useProductListingSorting` - Sorting functionality
+
+**The public API of `useListing` remains the same**, but internal implementation has changed significantly.
+
+### 6. SSR Improvements
+
+- **Removed `<ClientOnly>` wrappers** from filter components
+- Initial listing data is now provided via context during SSR
+- Components can access listing data synchronously on server and client
+
+**Impact:** No hydration mismatches, but ensure context is created during SSR.
+
+## Migration Guide
+
+### Before (prop drilling)
+
+```vue
+<template>
+  <SwProductListingFilters
+    :listing="listing"
+    @filter-change="handleFilterChange"
+  />
+</template>
+
+<script setup>
+const listing = useListing();
+</script>
+```
+
+### After (context-based)
+
+```vue
+<!-- In CmsPage.vue or layout -->
+<script setup>
+import { createCategoryListingContext } from "@shopware/composables";
+
+// Create context once at top level
+if (initialListing) {
+  createCategoryListingContext(initialListing);
+}
+</script>
+
+<!-- In any child component -->
+<template>
+  <SwProductListingFilters @filter-change="handleFilterChange" />
+</template>
+
+<script setup>
+// Access listing from context
+const listing = useCategoryListing();
+</script>
+```
+
+### Using the New Composables
+
+If you need fine-grained control, use the individual composables:
+
+```ts
+import {
+  useProductListingFilters,
+  useProductListingPagination,
+  useProductListingSorting,
+  useProductListingProducts,
+} from "@shopware/composables";
+
+// Access specific functionality
+const { getInitialFilters, getCurrentFilters } = useProductListingFilters();
+const { currentPage, totalPages, loadMore } = useProductListingPagination();
+const { getSortingOrders, changeCurrentSortingOrder } = useProductListingSorting();
+const { getElements, search } = useProductListingProducts();
+```
+
+## New Features
+
+### Helper Functions
+
+Added `getProductListingFromCmsPage` helper to extract listing data from CMS pages:
+
+```ts
+import { getProductListingFromCmsPage } from "@shopware/helpers";
+
+const listing = getProductListingFromCmsPage(cmsPage);
+```
+
+### Utility Functions
+
+New internal utilities for listing operations (exported from `utils.ts`):
+- Improved type safety with `ListingType` and `ShortcutFilterParam` types
+- Better merge strategies for listing criteria
+
+## What Changed
+
+### File Structure
+- Split monolithic `useListing.ts` (~500 lines) into focused modules
+- Each module handles a single responsibility
+- Better tree-shaking and code organization
+
+### Performance
+- Reduced prop drilling
+- More efficient reactive updates
+- Better separation of concerns
+
+### Developer Experience
+- Easier to test individual features
+- Clearer API boundaries
+- Better TypeScript inference
+- Simplified component templates

packages/cms-base-layer/app/components/SwProductListingFilters.vue

@@ -11,7 +11,7 @@ import { type LocationQueryRaw, useRoute, useRouter } from "vue-router";
 import { useCategoryListing } from "#imports";
 import type { Schemas, operations } from "#shopware";
 
-const props = defineProps<{
+defineProps<{
   content: CmsElementProductListing | CmsElementSidebarFilter;
   listingType?: string;
 }>();
@@ -48,7 +48,6 @@ const router = useRouter();
 
 const {
   changeCurrentSortingOrder,
-  getCurrentFilters,
   getCurrentSortingOrder,
   getInitialFilters,
   getSortingOrders,
@@ -233,10 +232,6 @@ async function invokeCleanFilters() {
   }
 }
 
-const isDefaultSidebarFilter =
-  props.content.type === "sidebar-filter" &&
-  props.content.config?.boxLayout?.value === "standard";
-
 const handleSortChange = (sortKey: string) => {
   currentSortingOrder.value = sortKey;
 };
@@ -269,63 +264,42 @@ const handleRemoveFilterChip = async (chip: {
       @remove="handleRemoveFilterChip"
     />
 
-    <ClientOnly>
-      <template #fallback>
-        <div class="self-stretch flex flex-col justify-start items-start gap-4">
-          <div
-            class="flex flex-row items-center justify-between w-full mb-4 py-3 border-b border-outline-outline-variant">
-            <div class="h-6 w-24 bg-surface-surface-container rounded animate-pulse"></div>
-            <div class="h-10 w-20 bg-surface-surface-container rounded animate-pulse"></div>
-          </div>
-          <div class="self-stretch flex flex-col justify-start items-start gap-4">
-            <div v-for="i in 5" :key="i" class="w-full">
-              <div class="self-stretch py-3 border-b border-outline-outline-variant flex justify-between items-center">
-                <div class="h-6 w-32 bg-surface-surface-container rounded animate-pulse"></div>
-                <div class="h-6 w-6 bg-surface-surface-container rounded animate-pulse"></div>
-              </div>
-            </div>
-          </div>
-        </div>
-      </template>
-      <div class="self-stretch flex flex-col justify-start items-start gap-4">
-        <div
-          class="flex flex-row items-center justify-between w-full mb-4 py-3 border-b border-outline-outline-variant">
-          <div class="flex-1 text-surface-on-surface text-base font-bold leading-normal">
-            {{ translations.listing.filters }}
-          </div>
-          <SwSortDropdown
-            :sort-options="getSortingOrders ?? []"
-            :current-sort="getCurrentSortingOrder ?? ''"
-            :label="translations.listing.sort"
-            @sort-change="handleSortChange"
-          />
+    <div class="self-stretch flex flex-col justify-start items-start gap-4">
+      <div
+        class="flex flex-row items-center justify-between w-full mb-4 py-3 border-b border-outline-outline-variant">
+        <div class="flex-1 text-surface-on-surface text-base font-bold leading-normal">
+          {{ translations.listing.filters }}
         </div>
+        <SwSortDropdown
+          :sort-options="getSortingOrders ?? []"
+          :current-sort="getCurrentSortingOrder ?? ''"
+          :label="translations.listing.sort"
+          @sort-change="handleSortChange"
+        />
       </div>
-    </ClientOnly>
+    </div>
     <!-- Filters List -->
-    <ClientOnly>
-      <div v-if="!getInitialFilters.length"
-        class="self-stretch flex flex-col justify-start items-start gap-4 animate-pulse">
-        <div v-for="i in 3" :key="i" class="w-full h-12 bg-surface-surface-container rounded"></div>
-      </div>
-      <div class="self-stretch flex flex-col justify-start items-start gap-4" v-else>
-        <SwProductListingFilter v-for="filter in getInitialFilters" :key="filter.id"
-          :filter="filter"
-          :selected-manufacturer="sidebarSelectedFilters.manufacturer"
-          :selected-properties="sidebarSelectedFilters.properties"
-          :selected-min-price="sidebarSelectedFilters['min-price']"
-          :selected-max-price="sidebarSelectedFilters['max-price']"
-          :selected-rating="sidebarSelectedFilters.rating"
-          :selected-shipping-free="sidebarSelectedFilters['shipping-free']"
-          @filter-change="handleFilterChange"
-          class="w-full" />
-        <div v-if="showResetFiltersButton" class="w-full">
-          <SwBaseButton variant="primary" size="medium" block @click="invokeCleanFilters" type="button">
-            {{ translations.listing.resetFilters }}
-            <span class="w-6 h-6 i-carbon-close-filled inline-block align-middle ml-2"></span>
-          </SwBaseButton>
-        </div>
+    <div v-if="!getInitialFilters.length"
+      class="self-stretch flex flex-col justify-start items-start gap-4 animate-pulse">
+      <div v-for="i in 3" :key="i" class="w-full h-12 bg-surface-surface-container rounded"></div>
+    </div>
+    <div class="self-stretch flex flex-col justify-start items-start gap-4" v-else>
+      <SwProductListingFilter v-for="filter in getInitialFilters" :key="filter.id"
+        :filter="filter"
+        :selected-manufacturer="sidebarSelectedFilters.manufacturer"
+        :selected-properties="sidebarSelectedFilters.properties"
+        :selected-min-price="sidebarSelectedFilters['min-price']"
+        :selected-max-price="sidebarSelectedFilters['max-price']"
+        :selected-rating="sidebarSelectedFilters.rating"
+        :selected-shipping-free="sidebarSelectedFilters['shipping-free']"
+        @filter-change="handleFilterChange"
+        class="w-full" />
+      <div v-if="showResetFiltersButton" class="w-full">
+        <SwBaseButton variant="primary" size="medium" block @click="invokeCleanFilters" type="button">
+          {{ translations.listing.resetFilters }}
+          <span class="w-6 h-6 i-carbon-close-filled inline-block align-middle ml-2"></span>
+        </SwBaseButton>
       </div>
-    </ClientOnly>
+    </div>
   </div>
 </template>

packages/cms-base-layer/app/components/public/cms/CmsPage.vue

@@ -2,9 +2,10 @@
 import {
   getBackgroundImageUrl,
   getCmsLayoutConfiguration,
+  getProductListingFromCmsPage,
 } from "@shopware/helpers";
 import { pascalCase } from "scule";
-import { computed, h, resolveComponent } from "vue";
+import { computed, h, resolveComponent, watchEffect } from "vue";
 import { createCategoryListingContext, useNavigationContext } from "#imports";
 import type { Schemas } from "#shopware";
 
@@ -13,10 +14,24 @@ const props = defineProps<{
 }>();
 
 const { routeName } = useNavigationContext();
-if (routeName.value === "frontend.navigation.page") {
-  createCategoryListingContext();
+
+// Function to initialize or update listing context
+function updateListingContext(content: Schemas["CmsPage"]) {
+  if (routeName.value === "frontend.navigation.page") {
+    const initialListing =
+      getProductListingFromCmsPage<Schemas["ProductListingResult"]>(content);
+
+    if (initialListing) {
+      createCategoryListingContext(initialListing);
+    }
+  }
 }
 
+// Watch for content changes and update context
+watchEffect(() => {
+  updateListingContext(props.content);
+});
+
 const cmsSections = computed<Schemas["CmsSection"][]>(() => {
   return props.content?.sections || [];
 });

packages/cms-base-layer/app/components/public/cms/element/CmsElementProductListing.vue

@@ -34,14 +34,10 @@ let translations: Translations = {
 };
 translations = defu(useCmsTranslations(), translations) as Translations;
 
-const {
-  changeCurrentPage,
-  getCurrentPage,
-  getElements,
-  getTotalPagesCount,
-  loading,
-  setInitialListing,
-} = useCategoryListing();
+// Use granular composables for better separation of concerns
+const listing = useCategoryListing();
+const { getElements, loading } = listing;
+const { changeCurrentPage, getCurrentPage, getTotalPagesCount } = listing;
 const route = useRoute();
 const router = useRouter();
 const limit = ref(
@@ -141,10 +137,6 @@ const compareRouteQueryWithInitialListing = async () => {
   }
 };
 
-setInitialListing(
-  props?.content?.data?.listing as Schemas["ProductListingResult"],
-);
-
 compareRouteQueryWithInitialListing();
 </script>