@faststore/core 4.5.0-dev.3 → 4.5.0-dev.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.5.0-dev.3",
+  "version": "4.5.0-dev.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/diagnostics": "4.5.0-dev.3",
-    "@faststore/lighthouse": "4.5.0-dev.3",
-    "@faststore/sdk": "4.5.0-dev.3",
-    "@faststore/api": "4.5.0-dev.3",
-    "@faststore/ui": "4.5.0-dev.3"
+    "@faststore/lighthouse": "4.5.0-dev.4",
+    "@faststore/api": "4.5.0-dev.4",
+    "@faststore/sdk": "4.5.0-dev.4",
+    "@faststore/ui": "4.5.0-dev.4",
+    "@faststore/diagnostics": "4.5.0-dev.4"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/components/sections/EmptyState/EmptyState.tsx

@@ -1,5 +1,5 @@
-import type { PropsWithChildren } from 'react'
 import { useRouter } from 'next/router'
+import type { PropsWithChildren } from 'react'
 
 import { Icon as UIIcon, Loader as UILoader } from '@faststore/ui'
 
@@ -9,8 +9,8 @@ import Section from '../Section'
 
 import styles from './section.module.scss'
 
-import { EmptyStateDefaultComponents } from './DefaultComponents'
 import { getOverridableSection } from '../../../sdk/overrides/getOverriddenSection'
+import { EmptyStateDefaultComponents } from './DefaultComponents'
 
 export interface EmptyStateProps {
   /**
@@ -53,11 +53,12 @@ const useErrorState = () => {
     query: { errorId, fromUrl },
     pathname,
     asPath,
+    locale,
   } = router
 
   return {
     errorId,
-    fromUrl: fromUrl ?? asPath ?? pathname,
+    fromUrl: fromUrl ?? (locale ? `/${locale}${asPath}` : asPath) ?? pathname,
   }
 }
 

package/src/components/templates/ProductListingPage/ProductListingPage.tsx

@@ -21,6 +21,7 @@ import type { PLPContentType } from 'src/server/cms/plp'
 
 import storeConfig from '../../../../discovery.config'
 import { faststoreLoader } from 'src/components/ui/Image/loader'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import ProductListing from './ProductListing'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 
@@ -142,43 +143,48 @@ export default function ProductListingPage({
     : undefined
 
   return (
-    <SearchProvider
-      onChange={applySearchState}
-      itemsPerPage={itemsPerPage}
-      shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
-      {...searchParams}
+    <LocalizedProductProvider
+      otherLocales={server.collection?.otherLocales}
+      urlSuffix=""
     >
-      {lcpImageUrl && (
-        <Head>
-          <link
-            rel="preload"
-            as="image"
-            href={lcpImageUrl}
-            fetchPriority="high"
-          />
-        </Head>
-      )}
-      {/* SEO */}
-      <NextSeo
-        title={title}
-        description={description}
-        titleTemplate={titleTemplate}
-        canonical={canonical}
-        openGraph={{
-          type: 'website',
-          title,
-          description,
-        }}
-      />
-      <BreadcrumbJsonLd itemListElements={itemListElements} />
-
-      <ProductListing
-        globalSections={globalSections}
-        globalSettings={globalSettings}
-        page={plpContentType}
-        data={server}
-        serverManyProductsVariables={serverManyProductsVariables}
-      />
-    </SearchProvider>
+      <SearchProvider
+        onChange={applySearchState}
+        itemsPerPage={itemsPerPage}
+        shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
+        {...searchParams}
+      >
+        {lcpImageUrl && (
+          <Head>
+            <link
+              rel="preload"
+              as="image"
+              href={lcpImageUrl}
+              fetchPriority="high"
+            />
+          </Head>
+        )}
+        {/* SEO */}
+        <NextSeo
+          title={title}
+          description={description}
+          titleTemplate={titleTemplate}
+          canonical={canonical}
+          openGraph={{
+            type: 'website',
+            title,
+            description,
+          }}
+        />
+        <BreadcrumbJsonLd itemListElements={itemListElements} />
+
+        <ProductListing
+          globalSections={globalSections}
+          globalSettings={globalSettings}
+          page={plpContentType}
+          data={server}
+          serverManyProductsVariables={serverManyProductsVariables}
+        />
+      </SearchProvider>
+    </LocalizedProductProvider>
   )
 }

package/src/components/ui/Breadcrumb/Breadcrumb.tsx

@@ -2,7 +2,6 @@ import type { BreadcrumbProps as UIBreadcrumbProps } from '@faststore/ui'
 import { Breadcrumb as UIBreadcrumb } from '@faststore/ui'
 import { memo } from 'react'
 
-import storeConfig from 'discovery.config'
 import Link from 'src/components/ui/Link'
 import { useOverrideComponents } from 'src/sdk/overrides/OverrideContext'
 export interface BreadcrumbProps extends UIBreadcrumbProps {
@@ -32,17 +31,11 @@ const Breadcrumb = ({ icon, alt, ...otherProps }: BreadcrumbProps) => {
           />
         </Link>
       }
-      renderLink={({ itemProps: { item: link, name } }) =>
-        // workaround to display the name without a link since localized slug is not available yet
-        // TODO: when localized slugs are available remove this workaround
-        storeConfig.localization?.enabled ? (
-          <span data-fs-breadcrumb-link>{name}</span>
-        ) : (
-          <Link data-fs-breadcrumb-link href={link} prefetch={false}>
-            {name}
-          </Link>
-        )
-      }
+      renderLink={({ itemProps: { item: link, name } }) => (
+        <Link data-fs-breadcrumb-link href={link} prefetch={false}>
+          {name}
+        </Link>
+      )}
       {...Breadcrumb.props}
       {...otherProps}
     />

package/src/components/ui/LocalizationButton/LocalizationButton.tsx

@@ -6,6 +6,7 @@ import { Icon, Button as UIButton } from '@faststore/ui'
 import storeConfig from 'discovery.config'
 import LocalizationSelector from 'src/components/localization/LocalizationSelector'
 import { useBindingSelector } from 'src/sdk/localization'
+import { useLocalizedProduct } from 'src/sdk/localization/LocalizedProductContext'
 import { useSession } from 'src/sdk/session'
 
 export interface LocalizationButtonErrorMessages {
@@ -41,6 +42,9 @@ const LocalizationButton = ({
   const [isSelectorOpen, setIsSelectorOpen] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
 
+  const otherLocales = useLocalizedProduct()?.otherLocales ?? undefined
+  const urlSuffix = useLocalizedProduct()?.urlSuffix ?? '/p'
+
   const {
     languages,
     currencies,
@@ -52,7 +56,7 @@ const LocalizationButton = ({
     reset,
     isSaveEnabled,
     error,
-  } = useBindingSelector()
+  } = useBindingSelector(otherLocales, urlSuffix)
 
   const { locale: sessionLocale, currency: sessionCurrency } = useSession()
 

package/src/experimental/index.ts

@@ -82,3 +82,5 @@ export type { UseBindingSelectorReturn } from '../sdk/localization/useBindingSel
 export { useLink as useLink_unstable } from '../sdk/ui/useLink'
 export { default as Link_unstable } from '../components/ui/Link'
 export { localizeRedirectDestination as localizeRedirectDestination_unstable } from '../utils/localization/localizeRedirectDestination'
+export { useLocalizedProduct as useLocalizedProduct_unstable } from '../sdk/localization/LocalizedProductContext'
+export type { LocalizedProductLocale as LocalizedProductLocale_unstable } from '../sdk/localization/LocalizedProductContext'

package/src/pages/[...slug].tsx

@@ -106,6 +106,10 @@ const query = gql(`
           value
         }
       }
+      otherLocales {
+        locale
+        slug
+      }
     }
   }
 `)
@@ -172,6 +176,7 @@ export const getStaticProps: GetStaticProps<
     >({
       variables: { slug },
       operation: query,
+      locale,
     }),
     contentService.getPlpContent(
       {

package/src/pages/[slug]/p.tsx

@@ -34,6 +34,7 @@ import {
   getGlobalSectionsData,
   type GlobalSectionsData,
 } from 'src/components/cms/GlobalSections'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 import { getOfferUrl, useOffer } from 'src/sdk/offer'
 import PageProvider, { type PDPContext } from 'src/sdk/overrides/PageProvider'
@@ -94,6 +95,46 @@ const overwriteMerge = (_: any[], sourceArray: any[]) => sourceArray
 const isClientOfferEnabled = (storeConfig as StoreConfig).experimental
   .enableClientOffer
 
+function buildHreflangLinks(
+  storeConfig: StoreConfig,
+  otherLocales: Array<{ locale: string; slug: string }> | null | undefined
+): Array<{ rel: string; hrefLang: string; href: string }> {
+  if (!storeConfig.localization?.enabled || !otherLocales?.length) return []
+
+  const locales = storeConfig.localization.locales
+  const baseStoreUrl = storeConfig.storeUrl.replace(/\/$/, '')
+  const defaultLocale = storeConfig.localization.defaultLocale
+  const links: Array<{ rel: string; hrefLang: string; href: string }> = []
+
+  for (const { locale, slug } of otherLocales) {
+    const bindingUrl = locales?.[locale]?.bindings?.[0]?.url
+    if (typeof bindingUrl === 'string' && bindingUrl.length > 0) {
+      links.push({
+        rel: 'alternate',
+        hrefLang: locale,
+        href: `${bindingUrl.replace(/\/$/, '')}/${slug}/p`,
+      })
+    }
+  }
+
+  // PREMISE: the default locale is served at the store root (no locale prefix),
+  // which is how Next.js i18n sub-path routing works — the `defaultLocale` has no
+  // prefix while other locales live under `/{locale}`. Hence `x-default` points to
+  // `${storeUrl}/{slug}/p`. If a store ever serves its default locale under a path
+  // prefix or a dedicated domain instead of the root, this href must be derived
+  // from that locale's binding URL instead of `storeUrl`.
+  const defaultEntry = otherLocales.find((e) => e.locale === defaultLocale)
+  if (defaultEntry) {
+    links.push({
+      rel: 'alternate',
+      hrefLang: 'x-default',
+      href: `${baseStoreUrl}/${defaultEntry.slug}/p`,
+    })
+  }
+
+  return links
+}
+
 function Page({
   data: server,
   sections,
@@ -136,6 +177,12 @@ function Page({
       product.offers.offers[0]?.itemCondition ?? ''
     ]
 
+  // hreflang alternate links for multi-locale stores
+  const hreflangLinks = buildHreflangLinks(
+    storeConfig as StoreConfig,
+    server.product.otherLocales
+  )
+
   let itemListElements = product.breadcrumbList.itemListElement ?? []
   if (itemListElements.length !== 0) {
     itemListElements = itemListElements.map(
@@ -245,13 +292,11 @@ function Page({
               ]
             : []),
         ]}
+        additionalLinkTags={hreflangLinks}
         titleTemplate={titleTemplate}
       />
 
-      {/* TODO: when localized slugs are available remove this workaround */}
-      {!storeConfig.localization?.enabled && (
-        <BreadcrumbJsonLd itemListElements={itemListElements} />
-      )}
+      <BreadcrumbJsonLd itemListElements={itemListElements} />
 
       <ProductJsonLd
         id={`${meta.canonical}${settings?.seo?.id ?? ''}`}
@@ -283,13 +328,15 @@ function Page({
         If needed, wrap your component in a <Section /> component
         (not the HTML tag) before rendering it here.
       */}
-      <PageProvider context={context}>
-        <RenderSections
-          sections={sections}
-          globalSections={globalSections}
-          components={COMPONENTS}
-        />
-      </PageProvider>
+      <LocalizedProductProvider otherLocales={server.product.otherLocales}>
+        <PageProvider context={context}>
+          <RenderSections
+            sections={sections}
+            globalSections={globalSections}
+            components={COMPONENTS}
+          />
+        </PageProvider>
+      </LocalizedProductProvider>
     </>
   )
 }
@@ -351,6 +398,11 @@ const query = gql(`
         productGroupID
       }
 
+      otherLocales {
+        locale
+        slug
+      }
+
       ...ProductDetailsFragment_product
     }
   }

package/src/sdk/localization/LocalizedProductContext.tsx

@@ -0,0 +1,65 @@
+import { createContext, useContext, useMemo } from 'react'
+import type { PropsWithChildren } from 'react'
+
+export interface LocalizedProductLocale {
+  locale: string
+  slug: string
+}
+
+interface LocalizedProductData {
+  /**
+   * Localized slug entries for all available locales of the current page.
+   * Null when localization is disabled or the page type does not support it.
+   */
+  otherLocales: LocalizedProductLocale[] | null
+  /**
+   * Suffix appended after the localized slug when building the redirect URL.
+   * Use '/p' for product pages (PDP), '' for collection/PLP pages.
+   */
+  urlSuffix: string
+}
+
+const LocalizedProductContext = createContext<LocalizedProductData | null>(null)
+
+type LocalizedProductProviderProps = Readonly<
+  PropsWithChildren<{
+    otherLocales: LocalizedProductLocale[] | null | undefined
+    /**
+     * Suffix to append to the localized slug when building the redirect URL.
+     * Defaults to '/p' (product pages). Pass '' for collection/PLP pages.
+     */
+    urlSuffix?: string
+  }>
+>
+
+/**
+ * Provides localized page data (otherLocales, urlSuffix) to any component in
+ * the tree — including global components like LocalizationButton that are
+ * not co-located with page sections.
+ *
+ * Set in p.tsx (PDP) and [...slug].tsx (PLP); returns null outside those pages.
+ */
+export function LocalizedProductProvider({
+  otherLocales,
+  urlSuffix = '/p',
+  children,
+}: LocalizedProductProviderProps) {
+  const value = useMemo(
+    () => ({ otherLocales: otherLocales ?? null, urlSuffix }),
+    [otherLocales, urlSuffix]
+  )
+
+  return (
+    <LocalizedProductContext.Provider value={value}>
+      {children}
+    </LocalizedProductContext.Provider>
+  )
+}
+
+/**
+ * Returns localized product data for the current page.
+ * Safe to call from any component — returns null outside a product page.
+ */
+export function useLocalizedProduct(): LocalizedProductData | null {
+  return useContext(LocalizedProductContext)
+}

package/src/sdk/localization/useBindingSelector.ts

@@ -9,8 +9,86 @@ import {
   isValidUrl,
   resolveBinding,
 } from './bindingSelector'
+import type { LocalizedProductLocale } from './LocalizedProductContext'
 import type { BindingSelectorError, Locale } from './types'
 
+const OTHER_LOCALES_STORAGE_PREFIX = 'fs:otherLocales:'
+
+/**
+ * Extracts the SKU id from a PDP-shaped pathname ("/.../{slug}-{skuId}/p").
+ * Slugs always end with "-{skuId}" (see `getSlug` in the API), so the id is the
+ * last "-"-separated segment of the path segment that precedes "/p".
+ * Returns null when the path is not a product page or has no numeric id.
+ */
+export function getSkuIdFromPdpPath(pathname: string): string | null {
+  const match = pathname.match(/\/([^/]+)\/p\/?$/) // NOSONAR
+  const skuId = match?.[1]?.split('-').pop()
+
+  return skuId && /^\d+$/.test(skuId) ? skuId : null
+}
+
+/**
+ * Persists the localized slug map for a product keyed by its SKU id. This lets
+ * the locale selector rebuild canonical localized product URLs even after the
+ * user lands on a context-less page (e.g. a 404 for a locale where the product
+ * is unavailable), where `otherLocales` is no longer provided by the page.
+ */
+export function persistOtherLocales(
+  otherLocales: LocalizedProductLocale[]
+): void {
+  if (typeof window === 'undefined' || !otherLocales.length) return
+
+  const skuId = otherLocales[0]?.slug.split('-').pop()
+  if (!skuId) return
+
+  try {
+    globalThis.sessionStorage.setItem(
+      `${OTHER_LOCALES_STORAGE_PREFIX}${skuId}`,
+      JSON.stringify(otherLocales)
+    )
+  } catch {
+    // sessionStorage may be unavailable (private mode/quota); non-critical.
+  }
+}
+
+function isLocalizedProductLocaleArray(
+  value: unknown
+): value is LocalizedProductLocale[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (item) =>
+        typeof item === 'object' &&
+        item !== null &&
+        typeof (item as Record<string, unknown>).locale === 'string' &&
+        typeof (item as Record<string, unknown>).slug === 'string'
+    )
+  )
+}
+
+/**
+ * Recovers a previously persisted localized slug map for the product referenced
+ * by the current PDP URL. Returns null when not on a PDP or nothing is stored.
+ */
+export function recoverOtherLocales(): LocalizedProductLocale[] | null {
+  if (typeof window === 'undefined') return null
+
+  const skuId = getSkuIdFromPdpPath(globalThis.location.pathname)
+  if (!skuId) return null
+
+  try {
+    const raw = globalThis.sessionStorage.getItem(
+      `${OTHER_LOCALES_STORAGE_PREFIX}${skuId}`
+    )
+
+    if (!raw) return null
+    const parsed: unknown = JSON.parse(raw)
+    return isLocalizedProductLocaleArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
 interface Currency {
   code: string
   name: string
@@ -64,9 +142,17 @@ export interface UseBindingSelectorReturn {
  * Hook that provides state and actions for the localization selector.
  * Manages locale selection, currency filtering, and binding resolution.
  *
+ * @param otherLocales - Optional list of localized slugs for the current page.
+ *   When provided (e.g. on PDP or PLP), the save action navigates to the
+ *   localized page URL instead of preserving the current page path verbatim.
+ * @param urlSuffix - Suffix appended after the slug when building the redirect URL.
+ *   Use '/p' for product pages (default) and '' for collection/PLP pages.
  * @returns Object with languages, currencies, selections, and actions
  */
-export function useBindingSelector(): UseBindingSelectorReturn {
+export function useBindingSelector(
+  otherLocales?: Array<{ locale: string; slug: string }> | null,
+  urlSuffix = '/p'
+): UseBindingSelectorReturn {
   const { locale: currentLocale, currency: currentCurrency } = useSession()
   const localizationConfig = storeConfig.localization as LocalizationConfig
 
@@ -96,6 +182,15 @@ export function useBindingSelector(): UseBindingSelectorReturn {
     }
   }, [currentCurrency?.code])
 
+  // Persist the product's localized slugs so a later locale switch can rebuild
+  // the canonical localized URL even from a context-less page (e.g. a 404).
+  // Only relevant on PDPs — PLP otherLocales are collection slugs, not products.
+  useEffect(() => {
+    if (urlSuffix === '/p' && otherLocales?.length) {
+      persistOtherLocales(otherLocales)
+    }
+  }, [otherLocales, urlSuffix])
+
   // Build language options with disambiguation - returns Record<localeCode, languageName>
   const languages = useMemo(
     () => buildLanguageOptions(localizationConfig.locales),
@@ -181,12 +276,60 @@ export function useBindingSelector(): UseBindingSelectorReturn {
       return
     }
 
-    // Redirect to binding URL, preserving the current page path and query string
-    window.location.href = buildRedirectUrl(
+    // Prefer the current page's localized slugs. When missing (e.g. we're on a
+    // 404 for a locale where the product is unavailable) recover the map that was
+    // persisted while on a working PDP, so we can still build the canonical
+    // localized product URL instead of dropping the user on the locale home.
+    const effectiveOtherLocales = otherLocales?.length
+      ? otherLocales
+      : recoverOtherLocales()
+
+    if (effectiveOtherLocales?.length) {
+      // 1. Target locale has a specific translation → use it
+      const localizedEntry = effectiveOtherLocales.find(
+        (e) => e.locale === localeCode
+      )
+
+      // 2. No translation for target locale → fall back to the default locale slug
+      //    (IS linkText, always in the default locale) to avoid carrying over a
+      //    translated slug from a different locale (e.g. Italian slug on es-ES).
+      //    For an unavailable target this yields a 404 at the product URL (expected).
+      const fallbackEntry = effectiveOtherLocales.find(
+        (e) => e.locale === localizationConfig.defaultLocale
+      )
+
+      const entry = localizedEntry ?? fallbackEntry
+
+      if (entry) {
+        const baseUrl = binding.url.replace(/\/$/, '')
+        globalThis.location.href = `${baseUrl}/${entry.slug}${urlSuffix}${globalThis.location.search}${globalThis.location.hash}`
+        return
+      }
+    }
+
+    // otherLocales is empty/null but we're still on a PDP: strip the stale slug.
+    if (globalThis.location.pathname.endsWith('/p')) {
+      globalThis.location.href = binding.url
+      return
+    }
+
+    // No localized slugs available (not even persisted): preserve the current
+    // page path under the target binding instead of dropping the user on the
+    // locale home. For a default-locale slug this resolves the product; for an
+    // unavailable/untranslated slug it yields a 404 at the product URL, never the
+    // locale root.
+    globalThis.location.href = buildRedirectUrl(
       binding.url,
-      `${window.location.pathname}${window.location.search}${window.location.hash}`
+      `${globalThis.location.pathname}${globalThis.location.search}${globalThis.location.hash}`
     )
-  }, [localeCode, currencyCode, localizationConfig.locales])
+  }, [
+    localeCode,
+    currencyCode,
+    localizationConfig.locales,
+    localizationConfig.defaultLocale,
+    otherLocales,
+    urlSuffix,
+  ])
 
   const isSaveEnabled = Boolean(localeCode && currencyCode && !error)
 

package/src/server/index.ts

@@ -34,6 +34,7 @@ interface ExecuteOptions<V = Record<string, unknown>> {
   operation: Operation
   variables: V
   query?: string | null
+  locale?: string
 }
 
 const persistedQueries = new Map()
@@ -98,7 +99,7 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
     cookies: Map<string, Record<string, string>> | null
   }
 }> => {
-  const { operation, variables, query: maybeQuery } = options
+  const { operation, variables, query: maybeQuery, locale } = options
   const { operationHash, operationName } = operation['__meta__']
 
   if (!persistedQueries.size) {
@@ -127,6 +128,14 @@ export const execute = async <V extends Maybe<{ [key: string]: unknown }>, D>(
 
   const contextValue = await contextFactory(envelopContext)
 
+  // Override the store-default locale with the per-request locale (if any) so
+  // localization-aware resolvers read it from ctx.storage.locale. Resolvers that
+  // carry their own locale (e.g. product/search via locator facets) still
+  // override this default inside their own resolution.
+  if (locale) {
+    contextValue.storage.locale = locale
+  }
+
   const { data, errors } = (await run({
     schema,
     document: parse(query),