feat: [SFCC-517][SEO-friedly URLs] Added stateToRoute and routeToState custom mapping (#275)

Replace InstantSearch's default `routing: true` (the built-in `simple`
state mapping plus the default `history` router) in the SFRA
`instantsearch-config.js` with a custom `router` and `stateMapping`. The
storefront query string on category and search results pages becomes
short and stable - for example
`?q=jacket&brand=Apple&size=M&sort=price-asc&page=2` - instead of the
index-prefixed, bracketed default.

This PR covers the URL routing (state/route mapping) only. The
`rel="canonical"` work is handled separately.

The mapping is a sample covering the facets the cartridge ships with.
Clients who add their own facet attributes extend the two functions.

## Before / after
Category landing page, size `L` selected (master-level record model):

Before (default `simple` mapping + default router):
```
.../s/RefArch/womens/clothing/tops/?zzgk_006_dx__RefArch__products__en_US[refinementList][variants.size][0]=L
```

After:
```
.../s/RefArch/womens/clothing/tops/?size=L
```

Pre-existing parameters in the URL are kept intact.

Author: ede-somogyi-algolia

cartridges/int_algolia_sfra/cartridge/static/default/js/algolia/instantsearch-config.js

@@ -52,11 +52,121 @@ function enableInstantSearch(config) {
         query: config.urlQuery,
     };
 
+    // Custom URL routing: short, stable URL keys (q, category, brand, size, color, store, price, sort, page, etc.)
+    // instead of the default `simple` mapping's index-prefixed keys, with `arrayFormat: 'repeat'
+    // so `?brand=Apple&brand=Samsung` replaces `?brand[0]=Apple&brand[1]=Samsung`.
+    const isMaster = algoliaData.recordModel === 'master-level' || algoliaData.recordModel === 'attribute-sliced';
+    const sizeAttribute = isMaster ? 'variants.size' : 'size';
+    const colorAttribute = isMaster ? 'variants.color' : 'color';
+    const storeAttribute = isMaster ? 'variants.storeAvailability' : 'storeAvailability';
+    const priceAttribute = isMaster ? 'variants.price.' + algoliaData.currencyCode : 'price.' + algoliaData.currencyCode;
+
+    /**
+     * Compresses a hierarchicalMenu uiState slot (which stores cumulative paths at
+     * every level) into one segment per level so the URL reads as one value per level.
+     * Assumes category display names do not contain ' > '.
+     * @param {string[]} levels Cumulative paths, e.g. ['Womens', 'Womens > Clothing']
+     * @returns {string[]} One segment per level, e.g. ['Womens', 'Clothing']
+     */
+    function compressBreadcrumb(levels) {
+        return levels.map(function (level, i) {
+            return i === 0 ? level : level.split(' > ').pop();
+        });
+    }
+
+    /**
+     * Rebuilds the cumulative-path form the hierarchicalMenu widget expects in uiState
+     * from the per-level segments carried in the URL. Inverse of compressBreadcrumb.
+     * @param {string[]} segments One segment per level, e.g. ['Womens', 'Clothing']
+     * @returns {string[]} Cumulative paths, e.g. ['Womens', 'Womens > Clothing']
+     */
+    function expandBreadcrumb(segments) {
+        return segments.map(function (_, i) {
+            return segments.slice(0, i + 1).join(' > ');
+        });
+    }
+
+    // URL keys this mapping owns. Anything else already on the URL (lang, utm_*, ...) is
+    // preserved across refinements so locale and marketing parameters are not stripped.
+    const routeKeys = ['q', 'category', 'newArrivals', 'newArrival', 'brand', 'color', 'size', 'store', 'price', 'sort', 'page'];
+
+    const router = instantsearch.routers.history({
+        createURL: function (params) {
+            const qsModule = params.qsModule;
+            const url = new URL(params.location.href);
+            const current = qsModule.parse(url.search.slice(1));
+            routeKeys.forEach(function (key) { delete current[key]; });
+            const merged = Object.assign({}, current, params.routeState);
+            url.search = qsModule.stringify(merged, { arrayFormat: 'repeat' });
+            return url.href;
+        }
+    });
+
+    const stateMapping = {
+        stateToRoute: function (uiState) {
+            var indexUiState = uiState[productsIndex] || {};
+            var route = {};
+            if (indexUiState.query) route.q = indexUiState.query;
+            if (indexUiState.page) route.page = indexUiState.page;
+            if (indexUiState.sortBy === productsIndex) route.sort = 'best';
+            if (indexUiState.sortBy === productsIndexPriceAsc) route.sort = 'price-asc';
+            if (indexUiState.sortBy === productsIndexPriceDesc) route.sort = 'price-desc';
+            if (indexUiState.hierarchicalMenu && indexUiState.hierarchicalMenu['__primary_category.0']) {
+                route.category = compressBreadcrumb(indexUiState.hierarchicalMenu['__primary_category.0']);
+            }
+            if (indexUiState.hierarchicalMenu && indexUiState.hierarchicalMenu['newArrivalsCategory.0']) {
+                route.newArrivals = compressBreadcrumb(indexUiState.hierarchicalMenu['newArrivalsCategory.0']);
+            }
+            if (indexUiState.toggle && indexUiState.toggle.newArrival) route.newArrival = '1';
+            if (indexUiState.refinementList) {
+                if (indexUiState.refinementList.brand) route.brand = indexUiState.refinementList.brand;
+                if (indexUiState.refinementList[sizeAttribute]) route.size = indexUiState.refinementList[sizeAttribute];
+                if (indexUiState.refinementList[colorAttribute]) route.color = indexUiState.refinementList[colorAttribute];
+                if (indexUiState.refinementList[storeAttribute]) route.store = indexUiState.refinementList[storeAttribute];
+            }
+            if (indexUiState.range && indexUiState.range[priceAttribute]) route.price = indexUiState.range[priceAttribute];
+            return route;
+        },
+        routeToState: function (route) {
+            var indexUiState = {};
+            if (route.q) indexUiState.query = route.q;
+            if (route.page) indexUiState.page = Number(route.page);
+            if (route.sort === 'best') indexUiState.sortBy = productsIndex;
+            if (route.sort === 'price-asc') indexUiState.sortBy = productsIndexPriceAsc;
+            if (route.sort === 'price-desc') indexUiState.sortBy = productsIndexPriceDesc;
+            if (route.category) {
+                indexUiState.hierarchicalMenu = indexUiState.hierarchicalMenu || {};
+                indexUiState.hierarchicalMenu['__primary_category.0'] = expandBreadcrumb([].concat(route.category));
+            }
+            if (route.newArrivals) {
+                indexUiState.hierarchicalMenu = indexUiState.hierarchicalMenu || {};
+                indexUiState.hierarchicalMenu['newArrivalsCategory.0'] = expandBreadcrumb([].concat(route.newArrivals));
+            }
+            if (route.newArrival === '1') indexUiState.toggle = { newArrival: true };
+            var refinementList = {};
+            if (route.brand) refinementList.brand = [].concat(route.brand);
+            if (route.size) refinementList[sizeAttribute] = [].concat(route.size);
+            if (route.color) refinementList[colorAttribute] = [].concat(route.color);
+            if (route.store) refinementList[storeAttribute] = [].concat(route.store);
+            if (Object.keys(refinementList).length) indexUiState.refinementList = refinementList;
+            if (route.price) {
+                indexUiState.range = {};
+                indexUiState.range[priceAttribute] = route.price;
+            }
+            var ui = {};
+            ui[productsIndex] = indexUiState;
+            if (route.q) {
+                ui[contentsIndex] = { query: route.q };
+            }
+            return ui;
+        }
+    };
+
     var search = instantsearch({
         indexName: productsIndex,
         searchClient: config.searchClient,
         initialUiState: initialUiState,
-        routing: true,
+        routing: { router: router, stateMapping: stateMapping },
     });
 
     if (algoliaData.enableInsights) {