@faststore/core 3.99.1 → 4.0.0-dev.1

package/src/components/localization/LocalizationSelector/LocalizationSelector.tsx

@@ -0,0 +1,320 @@
+import type { RefObject } from 'react'
+import { useMemo } from 'react'
+
+import type { PopoverProps } from '@faststore/ui'
+import {
+  SlideOver,
+  SlideOverHeader,
+  Button as UIButton,
+  Icon as UIIcon,
+  Popover as UIPopover,
+  SelectField as UISelectField,
+  useFadeEffect,
+} from '@faststore/ui'
+
+import type { BindingSelectorError } from 'src/sdk/localization'
+import useScreenResize from 'src/sdk/ui/useScreenResize'
+import styles from './section.module.scss'
+
+type SelectValue = string
+type SelectOptions = Record<string, string>
+
+interface LocalizationSelectorContentProps {
+  /** Language options - Record where key is locale code (e.g., "pt-BR") and value is language name (e.g., "Português") */
+  languages: SelectOptions
+  /** Currency options - Record where key is currency code and value is currency code */
+  currencies: SelectOptions
+  /** Currently selected locale code (e.g., "pt-BR") */
+  localeCode: SelectValue
+  /** Currently selected currency code (e.g., "BRL") */
+  currencyCode: SelectValue
+  /** Callback when locale code changes - receives locale code */
+  onLocaleChange: (code: string) => void
+  /** Callback when currency code changes - receives currency code */
+  onCurrencyChange: (code: string) => void
+  languageLabel: string
+  currencyLabel: string
+  description: string
+  saveLabel: string
+  /**
+   * When true, renders the Save button inside the content.
+   * Used by the desktop (Popover) variation.
+   */
+  showSaveButton?: boolean
+  onSave?: () => void
+  /** Whether the save button should be enabled */
+  isSaveEnabled?: boolean
+  /** Error message element to display */
+  errorMessage?: React.ReactNode
+}
+
+export interface LocalizationSelectorErrorMessages {
+  noBindingFound?: string
+  invalidUrl?: string
+  noCurrencies?: string
+  defaultError?: string
+}
+
+export interface LocalizationSelectorProps {
+  /**
+   * Controls whether the selector is open or closed.
+   */
+  isOpen: boolean
+  /**
+   * Called when the selector should be closed
+   * (outside click, close button or save action).
+   */
+  onClose: () => void
+  /**
+   * Reference element used to position the Popover on desktop.
+   */
+  triggerRef?: RefObject<HTMLElement>
+  /**
+   * Language options from useBindingSelector hook.
+   * Record where key is locale code (e.g., "pt-BR") and value is language name (e.g., "Português")
+   */
+  languages: SelectOptions
+  /**
+   * Currency options from useBindingSelector hook.
+   */
+  currencies: SelectOptions
+  /**
+   * Currently selected locale code from useBindingSelector hook (e.g., "pt-BR")
+   */
+  localeCode: SelectValue | null
+  /**
+   * Currently selected currency code from useBindingSelector hook (e.g., "BRL")
+   */
+  currencyCode: SelectValue | null
+  /**
+   * Callback when locale code changes - receives locale code and passes to hook's setLocaleCode
+   */
+  onLocaleChange: (code: string) => void
+  /**
+   * Callback when currency code changes - passes to hook's setCurrencyCode
+   */
+  onCurrencyChange: (code: string) => void
+  /**
+   * Callback when save is triggered - passes to hook's save
+   */
+  onSave: () => void
+  /**
+   * Whether save is enabled from useBindingSelector hook
+   */
+  isSaveEnabled: boolean
+  /**
+   * Error state from useBindingSelector hook
+   */
+  error: BindingSelectorError | null
+  /**
+   * Title displayed in mobile SlideOver header
+   */
+  title: string
+  languageLabel: string
+  currencyLabel: string
+  /**
+   * Description text
+   */
+  description: string
+  saveLabel: string
+  /**
+   * Custom error messages from CMS
+   */
+  errorMessages?: LocalizationSelectorErrorMessages
+  /**
+   * Desktop only: `Popover` placement relative to `triggerRef`.
+   * Defaults to `bottom-start`. Use `top-start` / `top-end` when the trigger sits
+   * near the bottom of the viewport (e.g. footer).
+   */
+  popoverPlacement?: PopoverProps['placement']
+}
+
+const LocalizationSelectorContent = ({
+  languages,
+  currencies,
+  localeCode,
+  currencyCode,
+  onLocaleChange,
+  onCurrencyChange,
+  languageLabel,
+  currencyLabel,
+  description,
+  saveLabel,
+  showSaveButton = false,
+  onSave,
+  isSaveEnabled = true,
+  errorMessage,
+}: LocalizationSelectorContentProps) => {
+  return (
+    <div data-fs-localization-selector-content>
+      <UISelectField
+        id="localization-selector-language"
+        label={languageLabel}
+        options={languages}
+        value={localeCode}
+        onChange={(event) => onLocaleChange(event.currentTarget.value)}
+      />
+
+      <UISelectField
+        id="localization-selector-currency"
+        label={currencyLabel}
+        options={currencies}
+        value={currencyCode}
+        onChange={(event) => onCurrencyChange(event.currentTarget.value)}
+        disabled={Object.keys(currencies).length === 0}
+      />
+
+      <p data-fs-localization-selector-description>{description}</p>
+
+      {errorMessage}
+
+      {showSaveButton && onSave && (
+        <div data-fs-localization-selector-actions>
+          <UIButton
+            variant="primary"
+            onClick={onSave}
+            disabled={!isSaveEnabled}
+          >
+            {saveLabel}
+          </UIButton>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Helper function to get error message for display
+ */
+function getErrorMessage(
+  error: BindingSelectorError,
+  errorMessages?: LocalizationSelectorErrorMessages
+): string {
+  return errorMessages?.[error.type] ?? errorMessages?.defaultError ?? ''
+}
+
+function LocalizationSelector({
+  isOpen,
+  onClose,
+  triggerRef,
+  languages,
+  currencies,
+  localeCode,
+  currencyCode,
+  onLocaleChange,
+  onCurrencyChange,
+  onSave,
+  isSaveEnabled,
+  error,
+  title,
+  languageLabel,
+  currencyLabel,
+  description,
+  saveLabel,
+  errorMessages,
+  popoverPlacement = 'bottom-start',
+}: LocalizationSelectorProps) {
+  const { loading, isDesktop } = useScreenResize()
+  const { fade, fadeOut } = useFadeEffect()
+
+  const handleSave = () => {
+    onSave()
+  }
+
+  const isDesktopDevice = useMemo(
+    () => !loading && Boolean(isDesktop),
+    [loading, isDesktop]
+  )
+
+  if (loading) {
+    return null
+  }
+
+  // Error display
+  const errorMessage = error && (
+    <div data-fs-localization-selector-error role="alert">
+      <UIIcon name="Warning" width={18} height={18} />
+      <span>{getErrorMessage(error, errorMessages)}</span>
+    </div>
+  )
+
+  if (isDesktopDevice) {
+    return (
+      <UIPopover
+        isOpen={isOpen}
+        placement={popoverPlacement}
+        triggerRef={triggerRef}
+        onDismiss={onClose}
+        enablePortal
+        data-fs-localization-selector
+        wrapperProps={{
+          className: `${styles.common} ${styles.desktop}`,
+        }}
+        content={
+          <LocalizationSelectorContent
+            languages={languages}
+            currencies={currencies}
+            localeCode={localeCode ?? ''}
+            currencyCode={currencyCode ?? ''}
+            onLocaleChange={onLocaleChange}
+            onCurrencyChange={onCurrencyChange}
+            languageLabel={languageLabel}
+            currencyLabel={currencyLabel}
+            description={description}
+            saveLabel={saveLabel}
+            showSaveButton
+            onSave={handleSave}
+            isSaveEnabled={isSaveEnabled}
+            errorMessage={errorMessage}
+          />
+        }
+      />
+    )
+  }
+
+  return (
+    <SlideOver
+      data-fs-localization-selector
+      data-fs-localization-selector-mobile
+      fade={fade}
+      onDismiss={fadeOut}
+      onTransitionEnd={() => fade === 'out' && onClose()}
+      isOpen={isOpen}
+      size="partial"
+      direction="bottomSide"
+      overlayProps={{
+        className: `${styles.common} ${styles.mobile}`,
+      }}
+    >
+      <SlideOverHeader onClose={fadeOut}>
+        <h2 data-fs-localization-selector-title>{title}</h2>
+      </SlideOverHeader>
+      <div data-fs-localization-selector-body>
+        <LocalizationSelectorContent
+          languages={languages}
+          currencies={currencies}
+          localeCode={localeCode ?? ''}
+          currencyCode={currencyCode ?? ''}
+          onLocaleChange={onLocaleChange}
+          onCurrencyChange={onCurrencyChange}
+          languageLabel={languageLabel}
+          currencyLabel={currencyLabel}
+          description={description}
+          saveLabel={saveLabel}
+          errorMessage={errorMessage}
+        />
+      </div>
+      <footer data-fs-localization-selector-footer>
+        <UIButton
+          variant="primary"
+          onClick={handleSave}
+          disabled={!isSaveEnabled}
+        >
+          {saveLabel}
+        </UIButton>
+      </footer>
+    </SlideOver>
+  )
+}
+
+export default LocalizationSelector

package/src/components/localization/LocalizationSelector/index.ts

@@ -0,0 +1 @@
+export { default } from './LocalizationSelector'

package/src/components/localization/LocalizationSelector/section.module.scss

@@ -0,0 +1,18 @@
+@use "sass:meta";
+
+.desktop {
+  @include meta.load-css("~@faststore/ui/src/components/molecules/Popover/styles.scss");
+}
+
+.mobile {
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Overlay/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/organisms/SlideOver/styles.scss");
+}
+
+.common {
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Icon/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Select/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Button/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/molecules/SelectField/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/organisms/LocalizationSelector/styles.scss");
+}

package/src/components/localization/index.ts

@@ -0,0 +1 @@
+export { default as LocalizationSelector } from './LocalizationSelector'

package/src/components/navigation/Navbar/Navbar.tsx

@@ -9,6 +9,7 @@ import CartToggle from 'src/components/cart/CartToggle'
 import type { SearchInputRef } from 'src/components/search/SearchInput'
 import SearchInput from 'src/components/search/SearchInput'
 import Link from 'src/components/ui/Link'
+import LocalizationButton from 'src/components/ui/LocalizationButton'
 import Logo from 'src/components/ui/Logo'
 import { useOverrideComponents } from 'src/sdk/overrides/OverrideContext'
 import { useSession } from 'src/sdk/session'
@@ -62,6 +63,23 @@ export interface NavbarProps {
     label: string
     shouldDisplayRegion: boolean
   }
+  /**
+   * Localization Button props.
+   */
+  localizationButton?: {
+    icon: string
+    shouldDisplayLocalizationButton: boolean
+  }
+  /**
+   * Localization Selector props.
+   */
+  localizationSelector?: {
+    title?: string
+    languageLabel?: string
+    currencyLabel?: string
+    description?: string
+    saveLabel?: string
+  }
   /**
    * Page links.
    */
@@ -84,6 +102,8 @@ function Navbar({
   links,
   signIn,
   region,
+  localizationButton,
+  localizationSelector,
   home: { label: homeLabel },
   signIn: { button: signInButton },
   menu: {
@@ -111,6 +131,9 @@ function Navbar({
   const isRepresentative = b2b?.isRepresentative
 
   const isOrganizationEnabled = isFaststoreMyAccountEnabled && isRepresentative
+  const isLocalizationEnabled =
+    storeConfig.localization?.enabled &&
+    localizationButton?.shouldDisplayLocalizationButton
 
   const handlerExpandSearch = useCallback(() => {
     setSearchExpanded(true)
@@ -154,6 +177,10 @@ function Navbar({
               placeholder={searchInput?.placeholder}
               sort={searchInput?.sort}
               quickOrderSettings={searchInput?.quickOrderSettings}
+              submitButtonAriaLabel={searchInput?.submitButtonAriaLabel}
+              loadingLabel={searchInput?.loadingLabel}
+              searchHistoryTitle={searchInput?.searchHistoryTitle}
+              searchTopTitle={searchInput?.searchTopTitle}
             />
           )}
 
@@ -164,7 +191,10 @@ function Navbar({
             {searchExpanded && (
               <IconButton.Component
                 data-fs-button-collapse
-                aria-label="Collapse search bar"
+                aria-label={
+                  searchInput?.collapseSearchAriaLabel ??
+                  IconButton.props['aria-label']
+                }
                 icon={<UIIcon name="CaretLeft" width={32} height={32} />}
                 {...IconButton.props}
                 // Dynamic props, shouldn't be overridable
@@ -182,10 +212,26 @@ function Navbar({
                 onSearchClick={handlerExpandSearch}
                 sort={searchInput?.sort}
                 quickOrderSettings={searchInput?.quickOrderSettings}
+                submitButtonAriaLabel={searchInput?.submitButtonAriaLabel}
                 hidden={!searchExpanded}
                 aria-hidden={!searchExpanded}
+                loadingLabel={searchInput?.loadingLabel}
+                searchHistoryTitle={searchInput?.searchHistoryTitle}
+                searchTopTitle={searchInput?.searchTopTitle}
               />
             )}
+
+            {isDesktop && isLocalizationEnabled && (
+              <LocalizationButton
+                icon={localizationButton?.icon}
+                title={localizationSelector?.title}
+                languageLabel={localizationSelector?.languageLabel}
+                currencyLabel={localizationSelector?.currencyLabel}
+                description={localizationSelector?.description}
+                saveLabel={localizationSelector?.saveLabel}
+              />
+            )}
+
             {isDesktop &&
               (isSessionReady ? (
                 isOrganizationEnabled ? (
@@ -217,6 +263,8 @@ function Navbar({
           links={links}
           signIn={signIn}
           region={region}
+          localizationButton={localizationButton}
+          localizationSelector={localizationSelector}
         />
       )}
     </NavbarWrapper.Component>

package/src/components/navigation/NavbarSlider/NavbarSlider.tsx

@@ -5,6 +5,7 @@ import storeConfig from 'discovery.config'
 import NavbarLinks from 'src/components/navigation/NavbarLinks'
 import { ButtonSignInFallback } from 'src/components/ui/Button'
 import Link from 'src/components/ui/Link'
+import LocalizationButton from 'src/components/ui/LocalizationButton'
 import Logo from 'src/components/ui/Logo'
 
 import type { NavbarProps } from '../Navbar'
@@ -20,12 +21,16 @@ interface NavbarSliderProps {
   links: NavbarProps['links']
   region: NavbarProps['region']
   signIn: NavbarProps['signIn']
+  localizationButton?: NavbarProps['localizationButton']
+  localizationSelector?: NavbarProps['localizationSelector']
 }
 
 function NavbarSlider({
   logo,
   links,
   region,
+  localizationButton,
+  localizationSelector,
   home: { label: homeLabel },
   signIn: { button: signInButton },
 }: NavbarSliderProps) {
@@ -45,9 +50,12 @@ function NavbarSlider({
     storeConfig.experimental?.enableFaststoreMyAccount
 
   const isRepresentative = b2b?.isRepresentative
-
   const isOrganizationEnabled = isFaststoreMyAccountEnabled && isRepresentative
 
+  const isLocalizationEnabled =
+    storeConfig.localization?.enabled &&
+    localizationButton?.shouldDisplayLocalizationButton
+
   return (
     <NavbarSliderWrapper.Component
       fade={fade}
@@ -92,6 +100,16 @@ function NavbarSlider({
             />
           )}
         </Suspense>
+        {isLocalizationEnabled && (
+          <LocalizationButton
+            icon={localizationButton?.icon}
+            title={localizationSelector?.title}
+            languageLabel={localizationSelector?.languageLabel}
+            currencyLabel={localizationSelector?.currencyLabel}
+            description={localizationSelector?.description}
+            saveLabel={localizationSelector?.saveLabel}
+          />
+        )}
       </NavbarSliderFooter.Component>
     </NavbarSliderWrapper.Component>
   )

package/src/components/navigation/NavbarSlider/section.module.scss

@@ -1,14 +1,16 @@
+@use "sass:meta";
+
 @layer components {
   .section {
-    @import "@faststore/ui/src/components/atoms/Button/styles.scss";
-    @import "@faststore/ui/src/components/atoms/Icon/styles.scss";
-    @import "@faststore/ui/src/components/atoms/Link/styles.scss";
-    @import "@faststore/ui/src/components/atoms/List/styles.scss";
-    @import "@faststore/ui/src/components/atoms/Logo/styles.scss";
-    @import "@faststore/ui/src/components/molecules/LinkButton/styles.scss";
-    @import "@faststore/ui/src/components/molecules/Modal/styles.scss";
-    @import "@faststore/ui/src/components/molecules/NavbarLinks/styles.scss";
-    @import "@faststore/ui/src/components/organisms/SlideOver/styles.scss";
-    @import "@faststore/ui/src/components/organisms/NavbarSlider/styles.scss";
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Button/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Icon/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Link/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/List/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/atoms/Logo/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/LinkButton/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/Modal/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/molecules/NavbarLinks/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/organisms/SlideOver/styles.scss");
+    @include meta.load-css("~@faststore/ui/src/components/organisms/NavbarSlider/styles.scss");
   }
 }

package/src/components/product/OutOfStock/OutOfStock.tsx

@@ -4,7 +4,11 @@ import { useState } from 'react'
 
 import { useSession } from 'src/sdk/session'
 
-function OutOfStock() {
+function OutOfStock({
+  loadingLabel,
+}: {
+  loadingLabel?: string
+}) {
   const { postalCode } = useSession()
 
   const [isLoading, setIsLoading] = useState(false)
@@ -44,6 +48,7 @@ function OutOfStock() {
       onSubmit={handleSubmit}
       disabled={isLoading}
       errorMessage={error}
+      loadingLabel={loadingLabel}
     />
   )
 }

package/src/components/product/ProductCard/ProductCard.tsx

@@ -82,7 +82,7 @@ function ProductCard({
   aspectRatio = 1,
   imgProps,
   ratingValue,
-  buttonLabel = 'Add',
+  buttonLabel,
   onButtonClick,
   showDiscountBadge = true,
   taxesConfiguration,

package/src/components/region/RegionModal/RegionModal.tsx

@@ -52,6 +52,7 @@ function RegionModal(regionModalProps: RegionModalProps) {
       noProductsAvailableErrorMessage:
         inputFieldNoProductsAvailableErrorMessage = '',
       buttonActionText: inputButtonActionText = '',
+      loadingLabel: inputLoadingLabel = '',
     } = {},
     idkPostalCodeLink: {
       text: idkPostalCodeLinkText = '',
@@ -135,7 +136,9 @@ function RegionModal(regionModalProps: RegionModalProps) {
             setInput('')
             setRegionError('')
           }}
-          inputButtonActionText={loading ? '...' : inputButtonActionText}
+          inputButtonActionText={
+            loading ? inputLoadingLabel : inputButtonActionText
+          }
           dismissible={isDismissible}
         />
       )}

package/src/components/region/RegionModal/section.module.scss

@@ -1,10 +1,12 @@
+@use "sass:meta";
+
 .section {
-  @import "@faststore/ui/src/components/atoms/Icon/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Input/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Overlay/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Button/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Link/styles.scss";
-  @import "@faststore/ui/src/components/molecules/InputField/styles.scss";
-  @import "@faststore/ui/src/components/molecules/Modal/styles.scss";
-  @import "@faststore/ui/src/components/organisms/RegionModal/styles.scss";
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Icon/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Input/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Overlay/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Button/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Link/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/molecules/InputField/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/molecules/Modal/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/organisms/RegionModal/styles.scss");
 }

package/src/components/region/RegionPopover/RegionPopover.tsx

@@ -46,11 +46,11 @@ interface RegionPopoverProps {
 
 function RegionPopover(regionPopoverProps: RegionPopoverProps) {
   const {
-    title = 'Set your location',
+    title,
     closeButtonAriaLabel,
-    textBeforeLocation = 'Your current location is:',
-    textAfterLocation = 'Use the field below to change it.',
-    description = 'Offers and availability vary by location.',
+    textBeforeLocation,
+    textAfterLocation,
+    description,
     triggerRef,
     offsetTop = 6,
     offsetLeft,
@@ -65,6 +65,7 @@ function RegionPopover(regionPopoverProps: RegionPopoverProps) {
       noProductsAvailableErrorMessage:
         inputFieldNoProductsAvailableErrorMessage = '',
       buttonActionText: inputButtonActionText = '',
+      loadingLabel: inputLoadingLabel = '',
     } = {},
     idkPostalCodeLink: {
       text: idkPostalCodeLinkText = '',
@@ -150,7 +151,7 @@ function RegionPopover(regionPopoverProps: RegionPopoverProps) {
           setInput('')
           setRegionError('')
         }}
-        buttonActionText={loading ? '...' : inputButtonActionText}
+        buttonActionText={loading ? inputLoadingLabel : inputButtonActionText}
         error={regionError}
       />
       {idkPostalCodeLinkTo && (

package/src/components/region/RegionPopover/section.module.scss

@@ -1,9 +1,11 @@
+@use "sass:meta";
+
 .section {
-  @import "@faststore/ui/src/components/atoms/Icon/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Input/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Button/styles.scss";
-  @import "@faststore/ui/src/components/atoms/Link/styles.scss";
-  @import "@faststore/ui/src/components/molecules/InputField/styles.scss";
-  @import "@faststore/ui/src/components/molecules/Popover/styles.scss";
-  @import "@faststore/ui/src/components/organisms/RegionPopover/styles.scss";
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Icon/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Input/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Button/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/atoms/Link/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/molecules/InputField/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/molecules/Popover/styles.scss");
+  @include meta.load-css("~@faststore/ui/src/components/organisms/RegionPopover/styles.scss");
 }