refactor(composables): product listing #2048

mkucmus · 2025-10-03T15:10:00Z

Refactor useListing composable for better modularity and SSR support

closes: #841
blocked by: #2030

Areas covered:

cms-base-layer
composables

Overview

Refactored the monolithic useListing composable into smaller, focused modules with improved SSR support and early data access for product listings (to avoid ClientOnly loading without hydration mismatch).

Changes

1. Modular Composable Architecture

Split useListing.ts into focused, single-responsibility composables:

useListingCore.ts - Core state management with provide/inject pattern
- Manages loading states, initial/applied listings
- Provides shared state via unique listingKey
- Includes dev-mode warnings for duplicate contexts
useProductListingProducts.ts - Product data and search operations
- Products list, total count
- search(), loadMore(), setInitialListing()
- Loading states
useProductListingPagination.ts - Pagination logic
- Current page, total pages, limit
- changeCurrentPage()
useProductListingSorting.ts - Sorting functionality
- Available sort orders
- Current sorting order
- changeCurrentSortingOrder()
useProductListingFilters.ts - Filter management
- Available/current filters
- setCurrentFilters(), resetFilters(), filtersToQuery()
utils.ts - Shared types and utilities
- Moved merge(), isObject() helpers
- Exported all TypeScript types for reuse

2. SSR Optimization

Early data access pattern:

getProductListingFromCmsPage.ts helper in @shopware/helpers
- Extracts product listing from CMS page structure
- Optimized algorithm with early exits and minimal allocations
- Returns null if no listing found
CmsPage.vue - Extract listing on component setup

  const initialListing = getProductListingFromCmsPage(props.content);
  if (initialListing) {
    createCategoryListingContext(initialListing);
  }

listing-related composables dependency graph

graph TD
    A[CmsPage.vue] -->|1. Extract listing from CMS| B[getProductListingFromCmsPage helper]
    B -->|2. Returns ProductListingResult or null| A
    A -->|3. Pass initialListing| C[createCategoryListingContext]
    
    C -->|4. Creates context with initialListing param| D[useListing composable]
    
    D -->|5. Pass initialListing| E[useListingCore]
    E -->|Provides shared state via inject/provide| F[Core State Management]
    
    F -.->|Injects core| G[useProductListingProducts]
    F -.->|Injects core| H[useProductListingPagination]
    F -.->|Injects core| I[useProductListingSorting]
    F -.->|Injects core| J[useProductListingFilters]
    
    D -->|6. Composes all modules| K[Facade Pattern useListing]
    K -->|Returns unified API| L[Components]
    
    L -->|Use listing composables| M[SwProductListingFilters.vue]
    L -->|Use listing composables| N[CmsElementProductListing.vue]
    L -->|Use listing composables| O[Search.vue]
    
    O -->|Manual setInitialListing call| G
    
    G -->|products, loading, search, loadMore| L
    H -->|pagination methods| L
    I -->|sorting methods| L
    J -->|filters methods| L
    
    P[utils.ts] -.->|Shared types & helpers| D
    P -.->|merge, isObject| E
    
    Q[Filter Components] -->|Use filter data| M
    Q1[SwFilterProperties.vue] -.-> Q
    Q2[SwFilterRating.vue] -.-> Q
    Q3[SwFilterPrice.vue] -.-> Q
    Q4[SwFilterShippingFree.vue] -.-> Q
    
    style A fill:#e1f5ff
    style E fill:#fff3e0
    style D fill:#f3e5f5
    style K fill:#e8f5e9
    style L fill:#fce4ec
    
    subgraph "SSR Flow (Category Pages)"
    A
    B
    C
    end
    
    subgraph "Core State Management"
    E
    F
    end
    
    subgraph "Modular Composables"
    G
    H
    I
    J
    end
    
    subgraph "UI Components"
    M
    N
    Q
    end
    
    subgraph "Manual Flow (Search)"
    O
    end

…/frontends into feat/product-listing-ui

vercel · 2025-10-03T15:10:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
frontends-demo	Ready	Preview	Oct 30, 2025 8:48am
frontends-vue-starter-template	Building	Preview	Oct 30, 2025 8:48am

1 Skipped Deployment

Project	Deployment	Preview	Updated (UTC)
shopware-frontends-docs	Skipped		Oct 30, 2025 8:48am

Copilot

Pull Request Overview

Refactored the monolithic useListing composable into smaller, focused modules to improve modularity, maintainability, and SSR support for product listings. The main goal is to enable early data access to avoid ClientOnly loading without hydration mismatches.

Split single large composable into focused, single-responsibility modules
Added SSR optimization with early data extraction from CMS pages
Improved filter component UI consistency and animations

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/helpers/src/cms/getProductListingFromCmsPage.ts	New helper to extract product listing data from CMS page structure for SSR optimization
packages/composables/src/useListing/useListingCore.ts	Core state management with provide/inject pattern and shared state
packages/composables/src/useListing/useProductListingProducts.ts	Products data and search operations module
packages/composables/src/useListing/useProductListingPagination.ts	Pagination logic module
packages/composables/src/useListing/useProductListingSorting.ts	Sorting functionality module
packages/composables/src/useListing/useProductListingFilters.ts	Filter management module
packages/composables/src/useListing/utils.ts	Shared types and utility functions
packages/composables/src/useListing/useListing.ts	Refactored facade that composes all modular composables
packages/cms-base-layer/app/components/public/cms/CmsPage.vue	Extract listing early and create context with initial listing
packages/cms-base-layer/app/components/SwProductListingFilters.vue	Removed ClientOnly wrappers and improved filter state management

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-03T15:14:17Z

packages/composables/src/useListing/useProductListingPagination.ts

+    await core.search(
+      Object.assign(
+        {
+          page,


The property should be 'p' instead of 'page' to match the API parameter format used elsewhere in the codebase (see line 116 in useProductListingProducts.ts where 'p: currentPage + 1' is used).

Suggested change

page,

p: page,

Copilot · 2025-10-03T15:14:17Z

packages/cms-base-layer/app/components/listing-filters/SwFilterShippingFree.vue

+    <Transition name="fade">
+      <div v-if="isFilterVisible" class="self-stretch pt-6">


The transition should include proper ARIA attributes for screen readers. Consider adding aria-expanded to the button and aria-hidden to the transition content to improve accessibility for users with disabilities.

Copilot · 2025-10-03T15:14:17Z

packages/cms-base-layer/app/components/listing-filters/SwFilterRating.vue

+    <Transition name="fade">
+      <div v-if="isFilterVisible" class="self-stretch flex flex-col justify-start items-start gap-4">


The transition should include proper ARIA attributes for screen readers. Consider adding aria-expanded to the button and aria-hidden to the transition content to improve accessibility for users with disabilities.

Copilot · 2025-10-03T15:14:18Z

packages/cms-base-layer/app/components/listing-filters/SwFilterProperties.vue

+    <Transition name="fade">
+      <div
+        v-if="isFilterVisible"
+        :id="props.filter.code"
+        class="self-stretch flex flex-col justify-start items-start gap-4"
+      >


The transition should include proper ARIA attributes for screen readers. Consider adding aria-expanded to the button and aria-hidden to the transition content to improve accessibility for users with disabilities.

Copilot · 2025-10-03T15:14:18Z

packages/cms-base-layer/app/components/listing-filters/SwFilterPrice.vue

+    <Transition name="fade">
+      <div v-if="isFilterVisible" :id="props.filter.code" class="self-stretch flex flex-col justify-start items-start gap-2.5">


The transition should include proper ARIA attributes for screen readers. Consider adding aria-expanded to the button and aria-hidden to the transition content to improve accessibility for users with disabilities.

mdanilowicz · 2025-11-02T19:28:57Z

packages/helpers/src/cms/getProductListingFromCmsPage.ts

+      for (const slot of block.slots) {
+        if (slot.type === "product-listing") {
+          const listing = slot.data?.listing;
+          if (listing) {
+            return listing as T;
+          }
+        }
+      }


Suggested change

for (const slot of block.slots) {

if (slot.type === "product-listing") {

const listing = slot.data?.listing;

if (listing) {

return listing as T;

}

}

}

const listing = block.slots

.find(slot => slot.type === "product-listing")

?.data?.listing as T | undefined;

if (listing) {

return listing;

}

mdanilowicz · 2025-11-02T19:34:19Z

packages/helpers/src/cms/getProductListingFromCmsPage.ts

+    sections: Array<{
+      blocks?: Array<{
+        slots?: Array<{
+          type?: string;
+          data?: Record<string, unknown> | null;
+        }>;
+      }>;
+    }>;


Suggested change

sections: Array<{

blocks?: Array<{

slots?: Array<{

type?: string;

data?: Record<string, unknown> | null;

}>;

}>;

}>;

sections: {

blocks?: {

slots?: {

type?: string;

data?: Record<string, unknown> | null;

}[];

}[];

}[];

Maybe this way will be more readable?

mdanilowicz · 2025-11-02T19:39:37Z

packages/composables/src/useListing/useProductListingSorting.ts

+    order: string,
+    query?: operations["searchPage post /search"]["body"],
+  ) => {
+    await core.search(


We had a discussion to not use API calls inside the composable. To make them more flexible and not dependent on the API client

mdanilowicz · 2025-11-02T19:41:32Z

packages/composables/src/useListing/useProductListingProducts.ts

+    initialListing: Schemas["ProductListingResult"],
+  ): Promise<void>;
+  /**
+   * @deprecated - use `search` instead


New composable and deprecation at the beginning :D?

mkucmus added 16 commits September 25, 2025 10:50

feat(cms-base-layer): apply new styling for product listing

5fa1b50

Merge remote-tracking branch 'origin/main' into feat/product-listing-ui

035b556

fix: types

5d05817

Merge branch 'main' into feat/product-listing-ui

ba7b9ab

chore: cleanup

64d2506

Merge branch 'feat/product-listing-ui' of https://github.com/shopware…

2a6ca6e

…/frontends into feat/product-listing-ui

fix: add missing theme colors

8b26482

chore: lint

5fd0f52

fix: replace old stuff

12516c5

fix: changes after CR

e848d7d

fix: hydration mismatch

290a29e

feat: category sidebar navigation

9ff8df4

fix: apply meteor chevron icon instead of carbon

a279ce0

fix: replace i-carbon icons with meteor

05577ec

fix: missing update

ef0eb16

refactor(composables): new structure of product listing

2332e64

vercel bot deployed to Preview – frontends-vue-starter-template October 3, 2025 15:10 View deployment

mkucmus added the pkg-pr-publish invoke publishing of specific PR to test that version label Oct 3, 2025

mkucmus requested a review from Copilot October 3, 2025 15:13

Copilot AI reviewed Oct 3, 2025

View reviewed changes

fix: helper types mismatch

34ed2ac

vercel bot deployed to Preview – shopware-frontends-docs October 3, 2025 15:24 View deployment

vercel bot deployed to Preview – frontends-vue-starter-template October 3, 2025 15:26 View deployment

vercel bot deployed to Preview – frontends-demo October 3, 2025 15:28 View deployment

chore: cleanup

c357182

vercel bot deployed to Preview – shopware-frontends-docs October 6, 2025 08:14 View deployment

vercel bot deployed to Preview – frontends-demo October 6, 2025 08:15 View deployment

vercel bot deployed to Preview – frontends-vue-starter-template October 6, 2025 08:17 View deployment

fix: CR fixes

0598f2d

chore: pnpm-lock update

f0670ba

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 10:44 View deployment

vercel bot deployed to Preview – frontends-demo October 29, 2025 10:47 View deployment

vercel bot deployed to Preview – shopware-frontends-docs October 29, 2025 10:48 View deployment

Merge branch 'feat/product-listing-ui' into refactor/product-listing

08ba4b7

vercel bot deployed to Preview – frontends-demo October 29, 2025 12:25 View deployment

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 12:27 View deployment

vercel bot deployed to Preview – shopware-frontends-docs October 29, 2025 12:27 View deployment

Merge remote-tracking branch 'origin/main' into refactor/product-listing

969143c

vercel bot temporarily deployed to Preview – shopware-frontends-docs October 29, 2025 12:38 Inactive

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 12:39 View deployment

vercel bot deployed to Preview – frontends-demo October 29, 2025 12:39 View deployment

feat: changeset

e666e0d

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 12:59 View deployment

vercel bot deployed to Preview – shopware-frontends-docs October 29, 2025 13:00 View deployment

vercel bot deployed to Preview – frontends-demo October 29, 2025 13:02 View deployment

fix: incompatibility issues

f796455

vercel bot deployed to Preview – shopware-frontends-docs October 29, 2025 16:13 View deployment

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 16:15 View deployment

vercel bot deployed to Preview – frontends-demo October 29, 2025 16:17 View deployment

fix: tests

726e863

vercel bot deployed to Preview – shopware-frontends-docs October 29, 2025 16:21 View deployment

vercel bot deployed to Preview – frontends-vue-starter-template October 29, 2025 16:22 View deployment

vercel bot deployed to Preview – frontends-demo October 29, 2025 16:24 View deployment

fix: remove redundant watchers

a6fe5b3

vercel bot temporarily deployed to Preview – shopware-frontends-docs October 30, 2025 08:48 Inactive

vercel bot deployed to Preview – frontends-vue-starter-template October 30, 2025 08:50 View deployment

vercel bot deployed to Preview – frontends-demo October 30, 2025 08:51 View deployment

mkucmus marked this pull request as ready for review October 30, 2025 09:40

mdanilowicz requested changes Nov 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(composables): product listing #2048

refactor(composables): product listing #2048

Uh oh!

mkucmus commented Oct 3, 2025 •

edited

Loading

Uh oh!

vercel bot commented Oct 3, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

Copilot AI Oct 3, 2025

Uh oh!

mdanilowicz Nov 2, 2025

Uh oh!

mdanilowicz Nov 2, 2025

Uh oh!

mdanilowicz Nov 2, 2025

Uh oh!

mdanilowicz Nov 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		<Transition name="fade">
		<div v-if="isFilterVisible" class="self-stretch pt-6">

		<Transition name="fade">
		<div v-if="isFilterVisible" :id="props.filter.code" class="self-stretch flex flex-col justify-start items-start gap-2.5">

refactor(composables): product listing #2048

Are you sure you want to change the base?

refactor(composables): product listing #2048

Uh oh!

Conversation

mkucmus commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Refactor useListing composable for better modularity and SSR support

Overview

Changes

1. Modular Composable Architecture

2. SSR Optimization

listing-related composables dependency graph

Uh oh!

vercel bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

mdanilowicz Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

mdanilowicz Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

mdanilowicz Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

mdanilowicz Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mkucmus commented Oct 3, 2025 •

edited

Loading

vercel bot commented Oct 3, 2025 •

edited

Loading