@usequeek/theme-kit 0.1.21 → 0.1.23

package/tests/language-switcher.test.tsx

@@ -0,0 +1,350 @@
+// @vitest-environment jsdom
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { act, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const nav = vi.hoisted(() => ({ pathname: '/', push: vi.fn() }));
+vi.mock('next/navigation', () => ({
+  usePathname: () => nav.pathname,
+  useRouter: () => ({ push: nav.push, replace: vi.fn(), back: vi.fn(), refresh: vi.fn() }),
+}));
+
+import { LanguageSwitcher } from '../components/language-switcher';
+import { useLocales, type LocalesState } from '../hooks/use-locales';
+import { StorefrontContext, StorefrontProvider } from '../provider';
+import type { ThemeManifest } from '../types/theme';
+import type { StoreLocaleInput } from '../utils/locale-switch';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const LOCALES: StoreLocaleInput[] = [
+  { locale: 'en', name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '', hreflang: 'en', html_lang: 'en', dir: 'ltr' },
+  { locale: 'fr', name: 'French', native_name: 'Français', is_primary: false, is_default: false, path_prefix: 'fr', hreflang: 'fr', html_lang: 'fr', dir: 'ltr' },
+  { locale: 'ar', name: 'Arabic', native_name: 'العربية', is_primary: false, is_default: false, path_prefix: 'ar', hreflang: 'ar', html_lang: 'ar', dir: 'rtl' },
+];
+
+interface ProviderOptions {
+  locales?: StoreLocaleInput[] | null;
+  locale?: string | null;
+  basePath?: string;
+  strings?: Record<string, unknown> | null;
+}
+
+function Provider({ options = {}, children }: { options?: ProviderOptions; children: ReactNode }) {
+  return (
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'acme', name: 'Acme' } as never}
+      config={{} as never}
+      menus={[]}
+      basePath={options.basePath ?? ''}
+      locale={options.locale ?? null}
+      {...(options.locales !== undefined ? { locales: options.locales } : {})}
+      {...(options.strings ? { strings: options.strings as never } : {})}
+    >
+      {children}
+    </StorefrontProvider>
+  );
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+function mount(node: ReactNode, options?: ProviderOptions): void {
+  act(() => {
+    root.render(<Provider options={options}>{node}</Provider>);
+  });
+}
+
+beforeEach(() => {
+  nav.pathname = '/shop';
+  nav.push.mockClear();
+  window.history.replaceState(null, '', '/shop');
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+describe('useLocales', () => {
+  function capture(options?: ProviderOptions): { current: LocalesState } {
+    const ref = {} as { current: LocalesState };
+    function Probe() {
+      ref.current = useLocales();
+      return null;
+    }
+    mount(<Probe />, options);
+    return ref;
+  }
+
+  it('reports a single-language state when no locales are passed', () => {
+    const state = capture();
+    expect(state.current.hasMultiple).toBe(false);
+    expect(state.current.locales).toEqual([]);
+    expect(state.current.active.locale).toBe('en');
+    expect(state.current.defaultLocale.path_prefix).toBe('');
+  });
+
+  it('reports a single-language state for one locale', () => {
+    const state = capture({ locales: [LOCALES[0]!] });
+    expect(state.current.hasMultiple).toBe(false);
+    expect(state.current.locales).toHaveLength(1);
+  });
+
+  it('does not throw outside a provider', () => {
+    const ref = {} as { current: LocalesState };
+    function Probe() {
+      ref.current = useLocales();
+      return null;
+    }
+    act(() => root.render(<Probe />));
+    expect(ref.current.hasMultiple).toBe(false);
+  });
+
+  it('exposes locales, default and the active language from the request locale', () => {
+    const state = capture({ locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    expect(state.current.hasMultiple).toBe(true);
+    expect(state.current.locales.map((l) => l.locale)).toEqual(['en', 'fr', 'ar']);
+    expect(state.current.defaultLocale.locale).toBe('en');
+    expect(state.current.active.locale).toBe('fr');
+  });
+
+  it('builds hrefFor from the pathname and picks up the query and hash after mount', () => {
+    nav.pathname = '/fr/shop';
+    window.history.replaceState(null, '', '/fr/shop?sort=new#top');
+    const state = capture({ locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    expect(state.current.hrefFor('en')).toBe('/shop?sort=new#top');
+    expect(state.current.hrefFor('ar')).toBe('/ar/shop?sort=new#top');
+    expect(state.current.hrefFor(state.current.locales[1]!)).toBe('/fr/shop?sort=new#top');
+    // Unknown code: stays on the current page.
+    expect(state.current.hrefFor('xx')).toBe('/fr/shop?sort=new#top');
+  });
+
+  it('switchTo pushes the live URL and ignores the active or an unknown language', () => {
+    const state = capture({ locales: LOCALES });
+    act(() => window.history.replaceState(null, '', '/shop?page=3'));
+    act(() => state.current.switchTo('fr'));
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop?page=3');
+    nav.push.mockClear();
+    act(() => state.current.switchTo('en'));
+    act(() => state.current.switchTo('xx'));
+    expect(nav.push).not.toHaveBeenCalled();
+  });
+});
+
+describe('LanguageSwitcher', () => {
+  /** What the switcher put on the page: the provider's brand wrapper stays, its content must be empty. */
+  const rendered = () => (container.querySelector('[data-brand-root]') ?? container).innerHTML;
+  const selectOf = () => container.querySelector('select') as HTMLSelectElement;
+
+  it('renders nothing with one language, none, or outside a storefront', () => {
+    mount(<LanguageSwitcher />);
+    expect(rendered()).toBe('');
+    mount(<LanguageSwitcher />, { locales: [LOCALES[0]!] });
+    expect(rendered()).toBe('');
+    act(() => root.render(<LanguageSwitcher />));
+    expect(rendered()).toBe('');
+  });
+
+  it('renders nothing on the server for a single language, and the control for several', () => {
+    const html = (locales?: StoreLocaleInput[]) =>
+      renderToStaticMarkup(
+        <Provider options={{ locales }}>
+          <LanguageSwitcher />
+        </Provider>,
+      );
+    expect(html()).not.toContain('qn-lang');
+    expect(html([LOCALES[0]!])).not.toContain('qn-lang');
+    expect(html(LOCALES)).toContain('data-qn-language-switcher');
+  });
+
+  it('renders a labelled native select with every language and the active one selected', () => {
+    mount(<LanguageSwitcher />, { locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    const group = container.querySelector('[data-qn-language-switcher]')!;
+    expect(group.getAttribute('role')).toBe('group');
+    expect(group.getAttribute('aria-label')).toBe('Language');
+    expect(selectOf().getAttribute('aria-label')).toBe('Language: French');
+    expect(selectOf().value).toBe('fr');
+    const options = [...container.querySelectorAll('option')];
+    expect(options.map((o) => o.textContent)).toEqual(['English', 'Français', 'العربية']);
+    expect(options.map((o) => o.getAttribute('lang'))).toEqual(['en', 'fr', 'ar']);
+    expect(options[2]!.getAttribute('dir')).toBe('rtl');
+    expect(options[0]!.getAttribute('dir')).toBe('ltr');
+  });
+
+  it('navigates when the selection changes (keyboard or pointer)', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    mount(<LanguageSwitcher />, { locales: LOCALES });
+    act(() => {
+      selectOf().value = 'fr';
+      selectOf().dispatchEvent(new Event('change', { bubbles: true }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop?sort=new');
+  });
+
+  it('goes back to the root path when the default language is chosen', () => {
+    nav.pathname = '/ar/products/mug';
+    mount(<LanguageSwitcher />, { locales: LOCALES, locale: 'ar', basePath: '/ar' });
+    act(() => {
+      selectOf().value = 'en';
+      selectOf().dispatchEvent(new Event('change', { bubbles: true }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/products/mug');
+  });
+
+  it('honours showCode and showNativeName, and className', () => {
+    mount(<LanguageSwitcher className="in-header" showCode showNativeName={false} />, { locales: LOCALES });
+    expect([...container.querySelectorAll('option')].map((o) => o.textContent)).toEqual([
+      'English · EN',
+      'French · FR',
+      'Arabic · AR',
+    ]);
+    expect(container.querySelector('[data-qn-language-switcher]')!.className).toBe('qn-lang qn-lang--select in-header');
+  });
+
+  it('takes its labels from the theme strings', () => {
+    mount(<LanguageSwitcher />, {
+      locales: LOCALES,
+      strings: { language: { label: 'Langue', named: 'Langue : {name}' } },
+    });
+    expect(container.querySelector('[role="group"]')!.getAttribute('aria-label')).toBe('Langue');
+    expect(selectOf().getAttribute('aria-label')).toBe('Langue : English');
+  });
+
+  it('renders the inline list with links, the current language marked, and wraps in a nav', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    mount(<LanguageSwitcher variant="inline-list" />, { locales: LOCALES, locale: null });
+    const nav_ = container.querySelector('nav')!;
+    expect(nav_.getAttribute('aria-label')).toBe('Language');
+    const links = [...container.querySelectorAll('a')];
+    expect(links.map((a) => a.getAttribute('href'))).toEqual(['/shop?sort=new', '/fr/shop?sort=new', '/ar/shop?sort=new']);
+    expect(links.map((a) => a.getAttribute('aria-current'))).toEqual(['true', null, null]);
+    expect(links[0]!.getAttribute('aria-label')).toBe('Language: English');
+    expect(links[1]!.getAttribute('lang')).toBe('fr');
+    expect(links[1]!.getAttribute('hreflang')).toBe('fr');
+  });
+
+  it('inline-list: a plain click switches with the live URL, a modified click is left alone', () => {
+    mount(<LanguageSwitcher variant="inline-list" />, { locales: LOCALES });
+    const fr = [...container.querySelectorAll('a')][1]!;
+    act(() => {
+      fr.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop');
+    nav.push.mockClear();
+    // jsdom cannot navigate: swallow the default action it would otherwise try.
+    const swallow = (event: Event) => event.preventDefault();
+    document.addEventListener('click', swallow);
+    const modified = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0, metaKey: true });
+    act(() => {
+      fr.dispatchEvent(modified);
+    });
+    document.removeEventListener('click', swallow);
+    expect(nav.push).not.toHaveBeenCalled();
+  });
+
+  it('hands the state to a render-prop and renders only what it returns', () => {
+    const seen: string[] = [];
+    mount(
+      <LanguageSwitcher>
+        {(state) => (
+          <ul data-testid="custom">
+            {state.locales.map((l) => {
+              seen.push(state.labelFor(l));
+              return (
+                <li key={l.locale}>
+                  <button type="button" onClick={() => state.switchTo(l)}>
+                    {state.displayName(l)}
+                  </button>
+                  <a href={state.hrefFor(l)}>{state.label}</a>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </LanguageSwitcher>,
+      { locales: LOCALES },
+    );
+    expect(container.querySelector('[data-qn-language-switcher]')).toBeNull();
+    expect(container.querySelector('select')).toBeNull();
+    expect(seen).toEqual(['Language: English', 'Language: French', 'Language: Arabic']);
+    act(() => {
+      (container.querySelectorAll('button')[1] as HTMLButtonElement).click();
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop');
+  });
+
+  it('the render-prop is not called for a single language', () => {
+    const children = vi.fn(() => <p>custom</p>);
+    mount(<LanguageSwitcher>{children}</LanguageSwitcher>, { locales: [LOCALES[0]!] });
+    expect(children).not.toHaveBeenCalled();
+    expect(rendered()).toBe('');
+  });
+
+  it('keeps the same markup on the server and on first client render (no hydration mismatch)', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    const tree = (
+      <Provider options={{ locales: LOCALES }}>
+        <LanguageSwitcher variant="inline-list" />
+      </Provider>
+    );
+    const server = renderToStaticMarkup(tree);
+    expect(server).toContain('href="/fr/shop"');
+    expect(server).not.toContain('sort=new');
+  });
+});
+
+describe('LanguageSwitcher styling', () => {
+  const css = readFileSync(join(__dirname, '..', 'components', 'language-switcher.css'), 'utf8');
+
+  it('uses logical properties only (right-to-left safe)', () => {
+    expect(css).not.toMatch(/(^|[\s{;])(left|right|margin-left|margin-right|padding-left|padding-right|border-left|border-right)\s*:/m);
+    expect(css).not.toMatch(/text-align:\s*(left|right)/);
+  });
+
+  it('styles only through --qn-* tokens, each with a fallback', () => {
+    const tokens = [...css.matchAll(/var\((--[a-z0-9-]+)/g)].map((m) => m[1]!);
+    expect(tokens.length).toBeGreaterThan(0);
+    expect(tokens.filter((t) => !t.startsWith('--qn-'))).toEqual([]);
+    expect(css).not.toMatch(/var\(--qn-[a-z0-9-]+\)/);
+  });
+});
+
+describe('provider', () => {
+  it('leaves the context untouched when no locales are passed (backward compatible)', () => {
+    let seen: unknown;
+    function Probe() {
+      seen = (globalThis as never as { __ctx?: unknown }).__ctx;
+      return null;
+    }
+    act(() =>
+      root.render(
+        <StorefrontProvider vendor={{ slug: 'acme' } as never} config={{} as never} menus={[]}>
+          <StorefrontContext.Consumer>
+            {(value) => {
+              (globalThis as never as { __ctx?: unknown }).__ctx = value;
+              return <Probe />;
+            }}
+          </StorefrontContext.Consumer>
+        </StorefrontProvider>,
+      ),
+    );
+    expect((seen as { locales: unknown[] }).locales).toEqual([]);
+    delete (globalThis as never as { __ctx?: unknown }).__ctx;
+  });
+});
+
+describe('theme manifest', () => {
+  it("declares the theme places the switcher with languageSwitcher: 'theme'", () => {
+    const field: Pick<ThemeManifest, 'languageSwitcher'> = { languageSwitcher: 'theme' };
+    const none: Pick<ThemeManifest, 'languageSwitcher'> = {};
+    expect(field.languageSwitcher).toBe('theme');
+    expect(none.languageSwitcher).toBeUndefined();
+  });
+});

package/tests/list-pagination.test.tsx

@@ -5,13 +5,13 @@ import { BlogPagination } from '../components/blog/pagination';
 import type { Pagination } from '../types/page';
 
 vi.mock('next/headers', () => ({
-  headers: async () => new Headers({ host: 'kili-foods.usequeek.com' }),
+  headers: async () => new Headers({ host: 'demo-store.usequeek.com' }),
 }));
 
 /**
  * Storefront lists answer `{data, has_more, next_cursor}` with no totals, page
- * counts or page URLs (founder 28/9/26: prev/next + "Page N", zero COUNT). The
- * kit's readers must walk on `has_more` alone and label the page they asked for.
+ * counts or page URLs (prev/next + "Page N", no COUNT query). The kit's
+ * readers must walk on `has_more` alone and label the page they asked for.
  */
 describe('storefront list walk state (has_more, no totals)', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -27,7 +27,7 @@ describe('storefront list walk state (has_more, no totals)', () => {
     vi.stubGlobal('fetch', fetchMock);
     const { fetchCollectionProducts } = await import('../api/collections');
 
-    const page3 = await fetchCollectionProducts('kili-foods', 'new-season', { page: 3, perPage: 20 });
+    const page3 = await fetchCollectionProducts('demo-store', 'new-season', { page: 3, perPage: 20 });
     expect(page3.pagination).toEqual({ current_page: 3, per_page: 20, has_more: true, next_cursor: 'eyJ2IjoxfQ' });
     const productsCall = fetchMock.mock.calls.map(([url]) => String(url)).find((url) => url.includes('/products'));
     expect(productsCall).toContain('page=3');
@@ -41,13 +41,13 @@ describe('storefront list walk state (has_more, no totals)', () => {
     })));
     const { fetchCollectionProducts } = await import('../api/collections');
 
-    const page = await fetchCollectionProducts('kili-foods', 'new-season');
+    const page = await fetchCollectionProducts('demo-store', 'new-season');
     expect(page.pagination).toEqual({ current_page: 1, per_page: undefined, has_more: false, next_cursor: null });
   });
 
   const renderPager = (pagination: Pagination, category?: string): string =>
     renderToStaticMarkup(
-      <StorefrontContext.Provider value={{ vendor: { id: 'v1', slug: 'kili-foods' }, basePath: '/kili-foods' } as never}>
+      <StorefrontContext.Provider value={{ vendor: { id: 'v1', slug: 'demo-store' }, basePath: '/demo-store' } as never}>
         <BlogPagination pagination={pagination} category={category} />
       </StorefrontContext.Provider>,
     );
@@ -56,8 +56,8 @@ describe('storefront list walk state (has_more, no totals)', () => {
     const html = renderPager({ current_page: 2, per_page: 12, has_more: true }, 'news');
     expect(html).toContain('Page 2');
     expect(html).not.toMatch(/Page 2 of/);
-    expect(html).toContain('rel="prev" href="/kili-foods/blog?category=news"');
-    expect(html).toContain('rel="next" href="/kili-foods/blog?category=news&amp;page=3"');
+    expect(html).toContain('rel="prev" href="/demo-store/blog?category=news"');
+    expect(html).toContain('rel="next" href="/demo-store/blog?category=news&amp;page=3"');
   });
 
   it('BlogPagination: last page disables Next; a lone first page renders nothing', () => {

package/tests/locale-switch.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import {
+  defaultStoreLocale,
+  localeHref,
+  normalizeStoreLocales,
+  resolveActiveLocale,
+  type StoreLocale,
+  type StoreLocaleInput,
+} from '../utils/locale-switch';
+
+function row(locale: string, extra: Partial<StoreLocaleInput> = {}): StoreLocaleInput {
+  return { locale, name: locale, native_name: locale, is_primary: false, ...extra };
+}
+
+/** English default, French and Simplified Chinese under prefixes. */
+const EN_DEFAULT = normalizeStoreLocales([
+  row('en', { name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '' }),
+  row('fr', { name: 'French', native_name: 'Français', is_default: false, path_prefix: 'fr' }),
+  row('zh-CN', { name: 'Chinese', native_name: '简体中文', is_default: false, path_prefix: 'zh-cn' }),
+]);
+
+/** French default; English (the primary) is not the default, so it lives under /en. */
+const FR_DEFAULT = normalizeStoreLocales([
+  row('fr', { name: 'French', native_name: 'Français', is_default: true, path_prefix: '' }),
+  row('en', { name: 'English', native_name: 'English', is_primary: true, is_default: false, path_prefix: 'en' }),
+]);
+
+function pick(locales: StoreLocale[], code: string): StoreLocale {
+  const found = locales.find((l) => l.locale === code);
+  if (!found) throw new Error(`fixture has no ${code}`);
+  return found;
+}
+
+function href(
+  locales: StoreLocale[],
+  from: string,
+  to: string,
+  url: { pathname: string; search?: string; hash?: string; basePath?: string },
+): string {
+  return localeHref({ ...url, active: pick(locales, from), target: pick(locales, to) });
+}
+
+describe('localeHref', () => {
+  it('moves the default language to a prefix and back to the root', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop' })).toBe('/fr/shop');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/shop', basePath: '/fr' })).toBe('/shop');
+  });
+
+  it('keeps the root path at the root of each language', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/' })).toBe('/fr');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr', basePath: '/fr' })).toBe('/');
+  });
+
+  it('puts English under /en when English is not the default', () => {
+    expect(href(FR_DEFAULT, 'fr', 'en', { pathname: '/shop' })).toBe('/en/shop');
+    expect(href(FR_DEFAULT, 'en', 'fr', { pathname: '/en/shop', basePath: '/en' })).toBe('/shop');
+  });
+
+  it('uses the lower-case code as the prefix (zh-CN -> /zh-cn)', () => {
+    expect(href(EN_DEFAULT, 'en', 'zh-CN', { pathname: '/products/mug' })).toBe('/zh-cn/products/mug');
+    expect(href(EN_DEFAULT, 'zh-CN', 'fr', { pathname: '/zh-cn/products/mug', basePath: '/zh-cn' })).toBe('/fr/products/mug');
+  });
+
+  it('switches directly between two prefixed languages', () => {
+    expect(href(EN_DEFAULT, 'fr', 'zh-CN', { pathname: '/fr/shop/all', basePath: '/fr' })).toBe('/zh-cn/shop/all');
+  });
+
+  it('keeps the query string and the hash', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: '?sort=new&page=2', hash: '#reviews' })).toBe(
+      '/fr/shop?sort=new&page=2#reviews',
+    );
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr', basePath: '/fr', search: '?q=a', hash: '#top' })).toBe('/?q=a#top');
+  });
+
+  it('accepts a query string and hash without their leading marks, and ignores empty ones', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: 'a=1', hash: 'x' })).toBe('/fr/shop?a=1#x');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: '?', hash: '#' })).toBe('/fr/shop');
+  });
+
+  it('keeps a trailing slash on a nested path', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop/' })).toBe('/fr/shop/');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/shop/mugs/', basePath: '/fr' })).toBe('/shop/mugs/');
+  });
+
+  it('only strips whole segments: a page that starts like a language is a page', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/french-press', basePath: '/fr' })).toBe('/french-press');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/french-press' })).toBe('/fr/french-press');
+    // Active is the default (no prefix to strip): `/fr` as a path is a page there.
+    expect(href(EN_DEFAULT, 'en', 'zh-CN', { pathname: '/fr-news' })).toBe('/zh-cn/fr-news');
+  });
+
+  it('strips the active prefix once: a page slug equal to the prefix survives', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/fr', basePath: '/fr' })).toBe('/fr');
+  });
+
+  it('handles a path-based host (basePath carries the store slug)', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/acme/shop', basePath: '/acme' })).toBe('/acme/fr/shop');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr/shop', basePath: '/acme/fr' })).toBe('/acme/shop');
+    expect(href(EN_DEFAULT, 'fr', 'zh-CN', { pathname: '/acme/fr', basePath: '/acme/fr' })).toBe('/acme/zh-cn');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr', basePath: '/acme/fr' })).toBe('/acme');
+  });
+
+  it('also copes with a non-localized basePath', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr/shop', basePath: '/acme' })).toBe('/acme/shop');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/acme', basePath: '/acme' })).toBe('/acme/fr');
+  });
+
+  it('matches the active prefix case-insensitively', () => {
+    expect(href(EN_DEFAULT, 'zh-CN', 'en', { pathname: '/ZH-CN/shop' })).toBe('/shop');
+  });
+
+  it('works on an old backend without is_default (primary is the default)', () => {
+    const old = normalizeStoreLocales([
+      { locale: 'en', name: 'English', native_name: 'English', is_primary: true, path_prefix: '' },
+      { locale: 'fr', name: 'French', native_name: 'Français', is_primary: false, path_prefix: 'fr' },
+    ]);
+    expect(old.map((l) => [l.locale, l.is_default, l.path_prefix])).toEqual([
+      ['en', true, ''],
+      ['fr', false, 'fr'],
+    ]);
+    expect(href(old, 'en', 'fr', { pathname: '/shop' })).toBe('/fr/shop');
+    expect(href(old, 'fr', 'en', { pathname: '/fr/shop', basePath: '/fr' })).toBe('/shop');
+  });
+});
+
+describe('normalizeStoreLocales', () => {
+  it('returns [] for nothing usable', () => {
+    expect(normalizeStoreLocales(undefined)).toEqual([]);
+    expect(normalizeStoreLocales(null)).toEqual([]);
+    expect(normalizeStoreLocales([])).toEqual([]);
+    expect(normalizeStoreLocales([{} as never, { locale: '' }, null as never])).toEqual([]);
+    expect(normalizeStoreLocales('fr' as never)).toEqual([]);
+  });
+
+  it('puts the default first and keeps the rest in order', () => {
+    const out = normalizeStoreLocales([
+      row('fr', { path_prefix: 'fr' }),
+      row('en', { is_primary: true, is_default: true }),
+      row('de', { path_prefix: 'de' }),
+    ]);
+    expect(out.map((l) => l.locale)).toEqual(['en', 'fr', 'de']);
+  });
+
+  it('keeps exactly one default, forces its prefix empty and fills empty prefixes', () => {
+    const out = normalizeStoreLocales([
+      row('en', { is_default: true, path_prefix: 'en' }),
+      row('FR', { is_default: true, path_prefix: '' }),
+      row('pt-BR', { path_prefix: '' }),
+    ]);
+    expect(out.map((l) => [l.locale, l.is_default, l.path_prefix])).toEqual([
+      ['en', true, ''],
+      ['FR', false, 'fr'],
+      ['pt-BR', false, 'pt-br'],
+    ]);
+  });
+
+  it('drops repeated codes, tolerates extra fields and defaults missing ones', () => {
+    const out = normalizeStoreLocales([
+      { locale: 'en', is_primary: true, extra: 'ignored' } as StoreLocaleInput,
+      { locale: 'EN', is_primary: false },
+      { locale: 'ar', path_prefix: 'ar', dir: 'rtl' },
+    ]);
+    expect(out).toHaveLength(2);
+    expect(out[0]).toMatchObject({ locale: 'en', name: 'en', native_name: 'en', dir: 'ltr', hreflang: 'en', html_lang: 'en' });
+    expect(out[0]).not.toHaveProperty('extra');
+    expect(out[1]?.dir).toBe('rtl');
+  });
+
+  it('accepts the storefront row shape without mapping', () => {
+    const storefrontRows: Array<{
+      locale: string; name: string; native_name: string; is_primary: boolean; is_default: boolean;
+      path_prefix: string; hreflang: string; html_lang: string; dir: string;
+    }> = [
+      { locale: 'en', name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '', hreflang: 'en', html_lang: 'en', dir: 'ltr' },
+    ];
+    const accepted: readonly StoreLocaleInput[] = storefrontRows;
+    const exact: StoreLocale = normalizeStoreLocales(accepted)[0]!;
+    // A storefront-typed value is assignable to StoreLocale as well.
+    const back: typeof storefrontRows[number] = exact;
+    expect(back.locale).toBe('en');
+  });
+});
+
+describe('active and default resolution', () => {
+  it('resolves the request locale case-insensitively, unknown/null to the default', () => {
+    expect(resolveActiveLocale(EN_DEFAULT, 'zh-cn').locale).toBe('zh-CN');
+    expect(resolveActiveLocale(EN_DEFAULT, 'fr').locale).toBe('fr');
+    expect(resolveActiveLocale(EN_DEFAULT, null).locale).toBe('en');
+    expect(resolveActiveLocale(EN_DEFAULT, 'xx').locale).toBe('en');
+    expect(resolveActiveLocale(FR_DEFAULT, undefined).locale).toBe('fr');
+  });
+
+  it('falls back to English for an empty list', () => {
+    expect(defaultStoreLocale([]).locale).toBe('en');
+    expect(resolveActiveLocale([], 'fr').path_prefix).toBe('');
+  });
+});

package/tests/locale-transport.test.tsx

@@ -16,7 +16,7 @@ import { normalizeShopQuery, type ShopPrefetch } from '../utils/shop-query';
 import type { Product } from '../types/product';
 
 /**
- * Theme-kit locale transport (slice K1): the backend answers `?locale=<code>`
+ * Theme-kit locale transport: the API answers `?locale=<code>`
  * with translated text, the proxy sets `x-queek-locale` for published
  * non-primary locales only, and every kit transport forwards it additively —
  * no locale anywhere means byte-identical behaviour to before.
@@ -194,7 +194,7 @@ describe('server transport (sdk/server-store-client)', () => {
 });
 
 describe('fetchShopPrefetch (api/shop)', () => {
-  async function runPrefetch(vendorSlug = 'kili-foods', locale?: string) {
+  async function runPrefetch(vendorSlug = 'demo-store', locale?: string) {
     const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => ({ ok: true, json: async () => ({ data: [], has_more: false }) }));
     vi.stubGlobal('fetch', fetchMock);
     const { fetchShopPrefetch } = await import('../api/shop');
@@ -226,7 +226,7 @@ function product(id: string, title: string): Product {
 function render(children: ReactNode, locale?: string | null): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(locale !== undefined ? { locale } : {})}

package/tests/markdown-render.test.ts

@@ -4,12 +4,11 @@ import { describe, expect, it } from 'vitest';
 import { renderMarkdown } from '../utils/markdown';
 
 /**
- * Backend CT16 (queek_backend/.agent/frontend-chat/sessions/storefront-contact-block/chat.json):
- * a heading immediately followed by other content, with no blank line between them, gets
- * swallowed whole into the heading — `utils/markdown.tsx` used to treat an entire
- * blank-line-delimited block as heading text the moment it matched a heading prefix. Real
- * merchant copy (Jhema Wears' short_description) writes "### Our Offerings\n- item\n- item"
- * with no blank line, which is common, valid markdown — the list must not disappear into the h3.
+ * A heading immediately followed by other content, with no blank line between them, must
+ * not be swallowed whole into the heading — `utils/markdown.tsx` once treated an entire
+ * blank-line-delimited block as heading text the moment it matched a heading prefix.
+ * Merchant copy often writes "### Our Offerings\n- item\n- item" with no blank line, which
+ * is common, valid markdown — the list must not disappear into the h3.
  */
 
 function html(markdown: string): string {