feat: persist search history by locale (#3231)

## What's the purpose of this pull request?

Stores with multiple locales shared one search history. This PR stores
history **per locale** so each language has its own list.

## How it works?

- Same IndexedDB key `fs::searchHistory`, but value is now
`Record<locale, History[]>` (e.g. `{ "en-US": [...], "pt-BR": [...] }`).
- `useSearchHistory` uses `useSession().locale` to read/write only the
current locale. Public API unchanged.
- Legacy array format is migrated on first load to the new shape (array
→ `{ defaultLocale: [...] }`).

## How to test it?

1. Run the store (`pnpm dev`).
2. In locale A: search a few terms, focus search again → history
appears.
3. Switch to locale B → history is empty (or only B’s terms).
4. Search in B, focus → only B’s terms. Switch back to A → A’s history
still there.
5. (Optional) DevTools → Application → IndexedDB → `fs::searchHistory` →
object with one key per locale.

<img width="1763" height="975" alt="image"
src="https://github.com/user-attachments/assets/abbb2d36-f8ba-48cf-aa74-c7f7e70bc362"
/>


### Starters Deploy Preview

https://brandless-cma5xay4001f6dn4xjwato8b4-mw8252v1z-vtex-fs.vercel.app/it-IT

https://brandless-cma5xay4001f6dn4xjwato8b4-mw8252v1z-vtex-fs.vercel.app/pt-BR
<!--- Add link to starter.store deploy preview for this branch. --->

## References

-
[SFS-2890](https://vtex-dev.atlassian.net/jira/software/c/projects/SFS/boards/1051?selectedIssue=SFS-2890)


[SFS-2890]:
https://vtex-dev.atlassian.net/browse/SFS-2890?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Search history is now locale-aware: each language/locale keeps its own
history and changes are isolated per locale.
* Legacy array-based histories are migrated automatically to the
locale-based format.

* **Behavior Improvements**
* History entries are deduplicated, newest-first, and capped to a
maximum size.
  * Clearing history removes only the active locale’s entries.

* **Tests**
* Comprehensive tests added for locale-aware history, migration,
deduplication, limits, and clearing behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: lemagnetic

packages/core/src/sdk/search/useSearchHistory.ts

@@ -1,35 +1,69 @@
 import { createStore } from '@faststore/sdk'
-
+import { useEffect, useMemo } from 'react'
+import config from 'discovery.config'
 import { useStore } from '../useStore'
+import { useSession } from '../session'
+
+export type SearchHistoryByLocale = Record<string, History[]>
 
 export const searchHistoryStore = createStore(
-  [] as History[],
+  {} as SearchHistoryByLocale,
   `fs::searchHistory`
 )
 
 const MAX_HISTORY_SIZE = 4
+const DEFAULT_LOCALE = config.localization.enabled
+  ? config.localization.defaultLocale
+  : config.session.locale
 
 export interface History {
   term: string
   path: string
 }
 
+function migrateSearchHistory(value: unknown): SearchHistoryByLocale {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as SearchHistoryByLocale
+  }
+  if (Array.isArray(value) && value.length > 0) {
+    return { [DEFAULT_LOCALE]: value as History[] }
+  }
+  return {}
+}
+
 export default function useSearchHistory(
   maxHistorySize: number = MAX_HISTORY_SIZE
 ) {
-  const searchHistory = useStore(searchHistoryStore)
+  const locale = useSession()?.locale ?? DEFAULT_LOCALE
+  const rawStore = useStore(searchHistoryStore)
+
+  const byLocale = useMemo(() => migrateSearchHistory(rawStore), [rawStore])
+
+  useEffect(() => {
+    if (Array.isArray(rawStore)) {
+      searchHistoryStore.set(migrateSearchHistory(rawStore))
+    }
+  }, [rawStore])
+
+  const searchHistory = byLocale[locale] ?? []
 
   function addToSearchHistory(newHistory: History) {
     const set = new Set<string>()
-    const newHistoryArray = [newHistory, ...searchHistory]
-      .slice(0, maxHistorySize)
+    const current = byLocale[locale] ?? []
+    const newHistoryArray = [newHistory, ...current]
       .filter((item) => !set.has(item.term) && set.add(item.term), set)
+      .slice(0, maxHistorySize)
 
-    searchHistoryStore.set(newHistoryArray)
+    searchHistoryStore.set({
+      ...byLocale,
+      [locale]: newHistoryArray,
+    })
   }
 
   function clearSearchHistory() {
-    searchHistoryStore.set([])
+    const next = { ...byLocale }
+    delete next[locale]
+    searchHistoryStore.set(Object.keys(next).length > 0 ? next : {})
   }
 
   return {

packages/core/test/sdk/search/useSearchHistory.test.ts

@@ -0,0 +1,222 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('discovery.config', () => ({
+  __esModule: true,
+  default: {
+    localization: { enabled: false, defaultLocale: 'pt-BR' },
+    session: { locale: 'en-US' },
+  },
+}))
+
+const mockUseSession = vi.hoisted(() => vi.fn(() => ({ locale: 'pt-BR' })))
+vi.mock('src/sdk/session', () => ({ useSession: mockUseSession }))
+
+import {
+  searchHistoryStore,
+  type History,
+} from '../../../src/sdk/search/useSearchHistory'
+import useSearchHistory from '../../../src/sdk/search/useSearchHistory'
+
+function makeHistory(term: string, path = `/s?q=${term}`) {
+  return { term, path } satisfies History
+}
+
+describe('useSearchHistory', () => {
+  beforeEach(() => {
+    searchHistoryStore.set({})
+    mockUseSession.mockReturnValue({ locale: 'pt-BR' })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('searchHistory (read by locale)', () => {
+    it('returns empty array when store is empty', () => {
+      const { result } = renderHook(() => useSearchHistory())
+      expect(result.current.searchHistory).toEqual([])
+    })
+
+    it('returns history for current locale when store has data for that locale', () => {
+      const items = [makeHistory('tenis'), makeHistory('camisa')]
+      searchHistoryStore.set({ 'pt-BR': items })
+
+      const { result } = renderHook(() => useSearchHistory())
+      expect(result.current.searchHistory).toEqual(items)
+    })
+
+    it('returns empty array when store has data only for another locale', () => {
+      searchHistoryStore.set({
+        'en-US': [makeHistory('shoes')],
+      })
+
+      const { result } = renderHook(() => useSearchHistory())
+      expect(result.current.searchHistory).toEqual([])
+    })
+
+    it('uses session locale and shows correct slice when locale changes', () => {
+      searchHistoryStore.set({
+        'pt-BR': [makeHistory('tenis')],
+        'en-US': [makeHistory('shoes')],
+      })
+
+      const { result, rerender } = renderHook(() => useSearchHistory())
+      expect(result.current.searchHistory).toEqual([makeHistory('tenis')])
+
+      mockUseSession.mockReturnValue({ locale: 'en-US' })
+      rerender()
+      expect(result.current.searchHistory).toEqual([makeHistory('shoes')])
+    })
+  })
+
+  describe('addToSearchHistory', () => {
+    it('adds item to current locale and persists', () => {
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => {
+        result.current.addToSearchHistory(makeHistory('tenis'))
+      })
+
+      expect(result.current.searchHistory).toHaveLength(1)
+      expect(result.current.searchHistory[0].term).toBe('tenis')
+      expect(searchHistoryStore.read()).toEqual({
+        'pt-BR': [makeHistory('tenis')],
+      })
+    })
+
+    it('dedupes by term and moves to front', () => {
+      searchHistoryStore.set({
+        'pt-BR': [makeHistory('camisa'), makeHistory('tenis')],
+      })
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => {
+        result.current.addToSearchHistory(
+          makeHistory('tenis', '/s?q=tenis&sort=score_desc')
+        )
+      })
+
+      expect(result.current.searchHistory.map((h) => h.term)).toEqual([
+        'tenis',
+        'camisa',
+      ])
+      expect(result.current.searchHistory).toHaveLength(2)
+    })
+
+    it('respects maxHistorySize (default 4)', () => {
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => result.current.addToSearchHistory(makeHistory('a')))
+      act(() => result.current.addToSearchHistory(makeHistory('b')))
+      act(() => result.current.addToSearchHistory(makeHistory('c')))
+      act(() => result.current.addToSearchHistory(makeHistory('d')))
+      act(() => result.current.addToSearchHistory(makeHistory('e')))
+
+      expect(result.current.searchHistory).toHaveLength(4)
+      expect(result.current.searchHistory.map((h) => h.term)).toEqual([
+        'e',
+        'd',
+        'c',
+        'b',
+      ])
+    })
+
+    it('can use custom maxHistorySize', () => {
+      const { result } = renderHook(() => useSearchHistory(2))
+
+      act(() => result.current.addToSearchHistory(makeHistory('a')))
+      act(() => result.current.addToSearchHistory(makeHistory('b')))
+      act(() => result.current.addToSearchHistory(makeHistory('c')))
+
+      expect(result.current.searchHistory).toHaveLength(2)
+      expect(result.current.searchHistory.map((h) => h.term)).toEqual([
+        'c',
+        'b',
+      ])
+    })
+
+    it('does not affect other locales', () => {
+      searchHistoryStore.set({
+        'en-US': [makeHistory('shoes')],
+      })
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => {
+        result.current.addToSearchHistory(makeHistory('tenis'))
+      })
+
+      expect(searchHistoryStore.read()).toEqual({
+        'en-US': [makeHistory('shoes')],
+        'pt-BR': [makeHistory('tenis')],
+      })
+    })
+  })
+
+  describe('clearSearchHistory', () => {
+    it('removes only current locale and leaves others', () => {
+      searchHistoryStore.set({
+        'pt-BR': [makeHistory('tenis')],
+        'en-US': [makeHistory('shoes')],
+      })
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => {
+        result.current.clearSearchHistory()
+      })
+
+      expect(result.current.searchHistory).toEqual([])
+      expect(searchHistoryStore.read()).toEqual({
+        'en-US': [makeHistory('shoes')],
+      })
+    })
+
+    it('sets store to empty object when clearing last locale', () => {
+      searchHistoryStore.set({ 'pt-BR': [makeHistory('tenis')] })
+      const { result } = renderHook(() => useSearchHistory())
+
+      act(() => {
+        result.current.clearSearchHistory()
+      })
+
+      expect(searchHistoryStore.read()).toEqual({})
+    })
+  })
+
+  describe('legacy format (array) migration', () => {
+    it('normalizes array to Record with default locale and exposes as searchHistory when session matches default', () => {
+      const legacy = [makeHistory('old1'), makeHistory('old2')]
+      searchHistoryStore.set(legacy as unknown as Record<string, History[]>)
+      mockUseSession.mockReturnValue({ locale: 'en-US' })
+
+      const { result } = renderHook(() => useSearchHistory())
+
+      expect(result.current.searchHistory).toHaveLength(2)
+      expect(result.current.searchHistory.map((h) => h.term)).toEqual([
+        'old1',
+        'old2',
+      ])
+    })
+
+    it('after migration persists Record so store no longer holds array', async () => {
+      const legacy = [makeHistory('old1')]
+      searchHistoryStore.set(legacy as unknown as Record<string, History[]>)
+      mockUseSession.mockReturnValue({ locale: 'en-US' })
+
+      renderHook(() => useSearchHistory())
+
+      await act(async () => {
+        await Promise.resolve()
+      })
+
+      const stored = searchHistoryStore.read()
+      expect(Array.isArray(stored)).toBe(false)
+      expect(stored).toHaveProperty('en-US')
+      expect((stored as Record<string, History[]>)['en-US']).toHaveLength(1)
+    })
+  })
+})