@akinon/pz-theme 2.0.117-rc.0 → 2.0.118-beta.0

package/src/utils/__tests__/localize-href.test.ts

@@ -0,0 +1,328 @@
+import {
+  isRootRelativeHref,
+  localizeHref,
+  localizeHtmlLinks
+} from '../localize-href';
+
+/**
+ * zsa-zsa-zsu's shape: Turkish is the default and hidden from the URL, English
+ * lives under `/en`. The matcher is what the core builds for that setup — only
+ * the non-default locale can appear as a segment.
+ */
+const store = {
+  defaultLocaleValue: 'tr',
+  localeUrlStrategy: 'hide-default-locale',
+  localeMatcher: /^\/(en)(?=\/|$)/
+};
+
+const onTurkish = { ...store, locale: 'tr' };
+const onEnglish = { ...store, locale: 'en' };
+
+describe('localizeHref under HideDefaultLocale', () => {
+  it('leaves a path alone on the default locale', () => {
+    expect(localizeHref('/x', onTurkish)).toBe('/x');
+    expect(localizeHref('/yatak-odasi/', onTurkish)).toBe('/yatak-odasi/');
+  });
+
+  it('prefixes a path on a non-default locale', () => {
+    expect(localizeHref('/x', onEnglish)).toBe('/en/x');
+    expect(localizeHref('/yatak-odasi/', onEnglish)).toBe('/en/yatak-odasi/');
+    expect(localizeHref('/baskets/basket', onEnglish)).toBe(
+      '/en/baskets/basket'
+    );
+    expect(localizeHref('/users/auth?next=%2Fbasket', onEnglish)).toBe(
+      '/en/users/auth?next=%2Fbasket'
+    );
+    expect(localizeHref('/', onEnglish)).toBe('/en/');
+  });
+
+  it('does not prefix a path that already carries the locale', () => {
+    expect(localizeHref('/en/x', onEnglish)).toBe('/en/x');
+    expect(localizeHref('/en', onEnglish)).toBe('/en');
+    expect(localizeHref(localizeHref('/x', onEnglish), onEnglish)).toBe(
+      '/en/x'
+    );
+  });
+
+  it('keeps an explicit other-locale link on the default locale', () => {
+    expect(localizeHref('/en/x', onTurkish)).toBe('/en/x');
+  });
+
+  it('trims the whitespace a pasted path brings with it', () => {
+    expect(localizeHref('  /x ', onEnglish)).toBe('/en/x');
+  });
+
+  it.each([
+    ['#a'],
+    ['?q=1'],
+    [''],
+    ['https://example.com/x'],
+    ['http://example.com'],
+    ['mailto:a@b.com'],
+    ['tel:+905551112233'],
+    ['//cdn.example.com/a.png'],
+    ['relative/path']
+  ])('leaves %p untouched on a non-default locale', (href) => {
+    expect(localizeHref(href, onEnglish)).toBe(href);
+  });
+
+  // The core OAuth middleware only matches these unprefixed.
+  it.each([
+    ['/google/login/'],
+    ['/apple/login'],
+    ['/google/login/?next=%2Fbasket'],
+    ['/google/login/callback/'],
+    ['/google/login/callback/?code=x']
+  ])('leaves the OAuth route %p unprefixed on an English page', (href) => {
+    expect(localizeHref(href, onEnglish)).toBe(href);
+  });
+
+  it('still prefixes paths that only look like a login route', () => {
+    expect(localizeHref('/users/login-help/', onEnglish)).toBe(
+      '/en/users/login-help/'
+    );
+    expect(localizeHref('/account/google/login/', onEnglish)).toBe(
+      '/en/account/google/login/'
+    );
+  });
+});
+
+/**
+ * The live home composition stores 42 of its links as the full address the
+ * merchant copied out of the browser. Next treats an absolute URL on its own
+ * origin as an internal route and prefetches it, which is what flips the
+ * `pz-locale` cookie back to Turkish.
+ */
+describe('localizeHref on a full URL to this storefront', () => {
+  const site = 'https://www.zsazsazsu.com.tr';
+  const english = { ...onEnglish, siteUrl: site };
+  const turkish = { ...onTurkish, siteUrl: site };
+
+  it('gives back the localized path, so the router can take it', () => {
+    expect(localizeHref(`${site}/yeni-urunler/`, english)).toBe(
+      '/en/yeni-urunler/'
+    );
+    expect(localizeHref(`${site}/liste?sort=new#top`, english)).toBe(
+      '/en/liste?sort=new#top'
+    );
+    expect(localizeHref(site, english)).toBe('/en/');
+  });
+
+  it('matches the same site with or without www, and http or https', () => {
+    expect(
+      localizeHref('https://zsazsazsu.com.tr/yeni-urunler/', english)
+    ).toBe('/en/yeni-urunler/');
+    expect(
+      localizeHref('http://www.zsazsazsu.com.tr/yeni-urunler/', english)
+    ).toBe('/en/yeni-urunler/');
+    expect(
+      localizeHref('https://www.zsazsazsu.com.tr/yeni-urunler/', {
+        ...english,
+        siteUrl: 'https://zsazsazsu.com.tr'
+      })
+    ).toBe('/en/yeni-urunler/');
+  });
+
+  it('leaves it exactly as written on the default locale', () => {
+    // The Turkish page keeps rendering the link the merchant stored.
+    expect(localizeHref(`${site}/yeni-urunler/`, turkish)).toBe(
+      `${site}/yeni-urunler/`
+    );
+  });
+
+  it('does not touch another site, a dev port or a broken URL', () => {
+    const elsewhere = 'https://lookbook.example.com/yeni-urunler/';
+    expect(localizeHref(elsewhere, english)).toBe(elsewhere);
+
+    // The port is part of the host: localhost:3000 is not the live store.
+    const localhost = 'http://localhost:3000/yeni-urunler/';
+    expect(localizeHref(localhost, english)).toBe(localhost);
+    expect(
+      localizeHref(localhost, { ...english, siteUrl: 'http://localhost:3000' })
+    ).toBe('/en/yeni-urunler/');
+
+    expect(localizeHref('https://', english)).toBe('https://');
+    expect(
+      localizeHref(`${site}/x`, { ...onEnglish, siteUrl: 'www.zsazsazsu' })
+    ).toBe(`${site}/x`);
+  });
+
+  it('leaves every full URL alone when the site address is unknown', () => {
+    expect(localizeHref(`${site}/yeni-urunler/`, onEnglish)).toBe(
+      `${site}/yeni-urunler/`
+    );
+  });
+
+  it('carries a locale the URL already has rather than stacking it', () => {
+    expect(localizeHref(`${site}/en/yeni-urunler/`, english)).toBe(
+      '/en/yeni-urunler/'
+    );
+    expect(localizeHref(localizeHref(`${site}/x`, english), english)).toBe(
+      '/en/x'
+    );
+  });
+});
+
+/**
+ * The brand middleware's matcher — `/((?!api|_next|…|[\w-/*]+\.\w+).*)` — never
+ * sees these, so there is no localized copy to point at: `/en/manifest.json`
+ * is a 404.
+ */
+describe('localizeHref on addresses with no localized copy', () => {
+  it.each([
+    ['/api/x'],
+    ['/api'],
+    ['/_next/static/chunk.js'],
+    ['/files/kvkk.pdf'],
+    ['/manifest.json'],
+    ['/files/sozlesme.pdf?v=2'],
+    ['/sitemap.xml#top']
+  ])('leaves %p unprefixed on an English page', (href) => {
+    expect(localizeHref(href, onEnglish)).toBe(href);
+  });
+
+  it('applies the same rule to a full URL of this storefront', () => {
+    const site = 'https://www.zsazsazsu.com.tr';
+    const english = { ...onEnglish, siteUrl: site };
+
+    expect(localizeHref(`${site}/files/kvkk.pdf`, english)).toBe(
+      `${site}/files/kvkk.pdf`
+    );
+  });
+
+  it('still prefixes paths that only contain a dot', () => {
+    expect(localizeHref('/kadin/elbise.ve.etek/', onEnglish)).toBe(
+      '/en/kadin/elbise.ve.etek/'
+    );
+    expect(localizeHref('/apikeys/', onEnglish)).toBe('/en/apikeys/');
+    expect(localizeHref('/_nextjs-guide/', onEnglish)).toBe(
+      '/en/_nextjs-guide/'
+    );
+  });
+});
+
+/**
+ * Blocks localize whatever they are handed, and some of them hand on a value
+ * that has been through here already — a stored URL read twice, a `ThemeLink`
+ * inside a `ThemeEditable`. The core matcher ends in `(?=/|$)`, so without
+ * splitting the query off first `/en?page=2` finds no locale to strip and
+ * becomes `/en/en?page=2`.
+ */
+describe('localizeHref is idempotent', () => {
+  it.each([
+    ['/en'],
+    ['/en/'],
+    ['/en/x'],
+    ['/en/x?page=2'],
+    ['/en?page=2'],
+    ['/en#top'],
+    ['/en/x?next=%2Fbasket#reviews']
+  ])('leaves the already-localized %p alone on an English page', (href) => {
+    expect(localizeHref(href, onEnglish)).toBe(href);
+  });
+
+  it.each([['/x'], ['/'], ['/x?page=2'], ['/x#top'], ['/yatak-odasi/']])(
+    'localizes %p once and the second pass changes nothing',
+    (href) => {
+      const once = localizeHref(href, onEnglish);
+
+      expect(localizeHref(once, onEnglish)).toBe(once);
+    }
+  );
+});
+
+describe('localizeHref under other strategies', () => {
+  it('prefixes every locale, the default too, under ShowAllLocales', () => {
+    const showAll = {
+      defaultLocaleValue: 'tr',
+      localeUrlStrategy: 'show-all-locales',
+      localeMatcher: /^\/(tr|en)(?=\/|$)/
+    };
+
+    expect(localizeHref('/x', { ...showAll, locale: 'tr' })).toBe('/tr/x');
+    expect(localizeHref('/x', { ...showAll, locale: 'en' })).toBe('/en/x');
+    // An existing locale is replaced, not stacked.
+    expect(localizeHref('/tr/x', { ...showAll, locale: 'en' })).toBe('/en/x');
+    expect(localizeHref('#a', { ...showAll, locale: 'en' })).toBe('#a');
+  });
+
+  it.each([['hide-all-locales'], ['subdomain']])(
+    'never prefixes under %s',
+    (localeUrlStrategy) => {
+      expect(
+        localizeHref('/x', { ...store, localeUrlStrategy, locale: 'en' })
+      ).toBe('/x');
+    }
+  );
+
+  it('changes nothing without a locale or a strategy', () => {
+    expect(localizeHref('/x', { ...store, locale: undefined })).toBe('/x');
+    expect(localizeHref('/x', { locale: 'en' })).toBe('/x');
+  });
+
+  it('prefixes without stripping when no matcher is given', () => {
+    expect(
+      localizeHref('/x', {
+        locale: 'en',
+        defaultLocaleValue: 'tr',
+        localeUrlStrategy: 'hide-default-locale'
+      })
+    ).toBe('/en/x');
+  });
+});
+
+describe('isRootRelativeHref', () => {
+  it('accepts a storefront path only', () => {
+    expect(isRootRelativeHref('/x')).toBe(true);
+    expect(isRootRelativeHref(' /x')).toBe(true);
+    expect(isRootRelativeHref('//cdn.example.com')).toBe(false);
+    expect(isRootRelativeHref('#a')).toBe(false);
+    expect(isRootRelativeHref('?q=1')).toBe(false);
+    expect(isRootRelativeHref('https://example.com')).toBe(false);
+    expect(isRootRelativeHref(undefined)).toBe(false);
+    expect(isRootRelativeHref({ pathname: '/x' })).toBe(false);
+  });
+});
+
+describe('localizeHtmlLinks', () => {
+  const toEnglish = (href: string) => localizeHref(href, onEnglish);
+
+  it('prefixes the storefront links in authored markup', () => {
+    expect(
+      localizeHtmlLinks(
+        'Detaylar için <a href="/kampanya/">tıklayın</a> ya da ' +
+          "<a class='c' href='/yatak-odasi/?sort=new'>göz atın</a>",
+        toEnglish
+      )
+    ).toBe(
+      'Detaylar için <a href="/en/kampanya/">tıklayın</a> ya da ' +
+        "<a class='c' href='/en/yatak-odasi/?sort=new'>göz atın</a>"
+    );
+  });
+
+  it('leaves everything that is not a storefront path byte for byte', () => {
+    const html =
+      '<p><a href="https://example.com/x" target="_blank">x</a>' +
+      '<a href="#faq">faq</a><a href="mailto:a@b.com">mail</a>' +
+      '<a href="/google/login/">google</a><a data-href="/x">no href</a>' +
+      '<link href="/x"><img src="/x.png"></p>';
+
+    expect(localizeHtmlLinks(html, toEnglish)).toBe(html);
+  });
+
+  it('keeps an apostrophe inside a double-quoted href', () => {
+    expect(localizeHtmlLinks(`<a href="/kadin's/">x</a>`, toEnglish)).toBe(
+      `<a href="/en/kadin's/">x</a>`
+    );
+  });
+
+  it('changes nothing on the default locale or without markup', () => {
+    const html = '<a href="/kampanya/">x</a>';
+
+    expect(
+      localizeHtmlLinks(html, (href) => localizeHref(href, onTurkish))
+    ).toBe(html);
+    expect(localizeHtmlLinks('plain text', toEnglish)).toBe('plain text');
+    expect(localizeHtmlLinks('', toEnglish)).toBe('');
+  });
+});

package/src/utils/localize-href.ts

@@ -0,0 +1,192 @@
+import { LocaleUrlStrategy } from '@akinon/next/localization';
+
+/**
+ * The storefront's locale settings, as `useLocalization()` hands them out.
+ *
+ * `localeMatcher` finds a locale segment an href already starts with — the
+ * core's `urlLocaleMatcherRegex` in the app, passed in so the rules below stay
+ * a pure function of their arguments.
+ *
+ * `siteUrl` is the storefront's own address (`NEXT_PUBLIC_URL`), which is what
+ * makes a merchant's full URL recognizable as one of these pages rather than
+ * somewhere else on the web. Without it a full URL is always left alone.
+ */
+export interface HrefLocale {
+  locale?: string;
+  defaultLocaleValue?: string;
+  localeUrlStrategy?: string;
+  localeMatcher?: RegExp;
+  siteUrl?: string;
+}
+
+/**
+ * Only a path on this storefront (`/yatak-odasi/`) has a locale to carry.
+ * `//cdn…` starts with a slash but is another host; a bare `#anchor` or
+ * `?page=2` is relative to the page the shopper is already on, which already
+ * has its locale, and prefixing it would drop that page's path instead.
+ */
+export const isRootRelativeHref = (href: unknown): href is string =>
+  typeof href === 'string' &&
+  href.trim().startsWith('/') &&
+  !href.trim().startsWith('//');
+
+/**
+ * `/{provider}/login/` and its `/callback/`: the core `withOauthLogin`
+ * middleware runs before the locale one and matches only the unprefixed path
+ * (`^/(\w+)/login(/callback)?/?$`), so `/en/google/login/` would miss it and
+ * fall through to a page that does not exist. Every `/{word}/login/` is OAuth
+ * to the core, so leaving these alone costs no storefront page.
+ */
+const OAUTH_ROUTE = /^\/\w+\/login(?:\/callback)?\/?(?:[?#]|$)/;
+
+/**
+ * A path split into the part a locale goes in front of and the `?query#hash`
+ * that has to ride along untouched. The core's `urlLocaleMatcherRegex` ends in
+ * `(?=/|$)`, so on `/en?page=2` it finds nothing to strip and the locale would
+ * be stacked into `/en/en?page=2` — which is what a second pass over an
+ * already-localized href does, and blocks localize whatever they are handed.
+ */
+const splitQuery = (path: string): [string, string] => {
+  const at = path.search(/[?#]/);
+  return at === -1 ? [path, ''] : [path.slice(0, at), path.slice(at)];
+};
+
+/**
+ * Addresses the storefront serves only one copy of: the API, Next's own
+ * assets, and anything ending in a file (`/files/kvkk.pdf`, `/manifest.json`).
+ * This is the brand middleware's matcher — `/((?!api|_next|…|[\w-/*]+\.\w+).*)`
+ * — read the other way round: the locale middleware never sees these, so `/en`
+ * in front of one is a 404 rather than a translation.
+ */
+const hasNoLocaleVariant = (path: string): boolean => {
+  const [pathname] = splitQuery(path);
+
+  if (/^\/(?:api|_next)(?:\/|$)/.test(pathname)) return true;
+
+  const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  return /\.[^.]+$/.test(lastSegment);
+};
+
+/**
+ * `www.` is not a different site. A merchant pastes whichever host their
+ * browser showed them, and the storefront answers on both.
+ */
+const siteHost = (host: string): string =>
+  host.toLowerCase().replace(/^www\./, '');
+
+/**
+ * A full URL of this storefront's own (`https://www.zsazsazsu.com.tr/yeni-urunler/`)
+ * as the path it points at, or nothing when it points somewhere else.
+ *
+ * Merchants paste the address bar, so most stored links are full URLs — 42 of
+ * them on the live home page alone. Next's app router treats an absolute URL
+ * on the same origin as an internal route: it prefetches it, the middleware
+ * answers that unprefixed path with `pz-locale=tr`, and the English page the
+ * shopper is reading starts serving Turkish. The port is part of the host
+ * comparison, so a dev storefront on :3000 is not confused with production.
+ */
+export const asSitePath = (
+  href: string,
+  siteUrl?: string
+): string | undefined => {
+  if (!siteUrl || !/^https?:\/\//i.test(href)) return undefined;
+
+  try {
+    const url = new URL(href);
+    const site = new URL(siteUrl);
+
+    if (siteHost(url.host) !== siteHost(site.host)) return undefined;
+
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    // A malformed URL is not this function's to fix: the href goes out as the
+    // merchant wrote it, the same as any other address we do not recognize.
+    return undefined;
+  }
+};
+
+/**
+ * `href` as it has to be written on a page in `locale`.
+ *
+ * Content stores storefront paths without a locale (`/yatak-odasi/`), and on
+ * an English page that path IS the Turkish site: a click leaves the English
+ * site, and every prefetch of it makes the middleware answer with
+ * `pz-locale=tr`, which every client request after it then sends as its
+ * language. So the same rules as `@akinon/next`'s own `Link` are applied here:
+ * strip a locale the href already carries, then prefix the active one when the
+ * URL strategy shows it — always for ShowAllLocales, and for HideDefaultLocale
+ * only off the default locale. The other strategies never carry a locale.
+ *
+ * A full URL of this storefront's own counts as one of those paths (see
+ * `asSitePath`), and on a page that shows its locale it comes back as the
+ * root-relative localized path — which is also what lets the router take it
+ * client-side. On a page that hides its locale it is returned exactly as
+ * given, so the Turkish site keeps rendering the links it always had.
+ *
+ * Unlike the core `Link`, anything else that is not a root-relative path comes
+ * back untouched rather than being turned into `#` or `/<locale>#anchor`:
+ * blocks route hash, query, empty and external hrefs through here as well. The
+ * OAuth routes (see `OAUTH_ROUTE`) and the addresses with no localized copy
+ * (see `hasNoLocaleVariant`) are left alone too.
+ */
+export const localizeHref = (
+  href: string,
+  {
+    locale,
+    defaultLocaleValue,
+    localeUrlStrategy,
+    localeMatcher,
+    siteUrl
+  }: HrefLocale
+): string => {
+  if (!locale || typeof href !== 'string') return href;
+
+  const path = asSitePath(href.trim(), siteUrl) ?? href.trim();
+
+  if (!isRootRelativeHref(path)) return href;
+  if (OAUTH_ROUTE.test(path)) return href;
+  if (hasNoLocaleVariant(path)) return href;
+
+  const showsLocale =
+    localeUrlStrategy === LocaleUrlStrategy.ShowAllLocales ||
+    (localeUrlStrategy === LocaleUrlStrategy.HideDefaultLocale &&
+      locale !== defaultLocaleValue);
+
+  if (!showsLocale) return href;
+
+  const [pathname, query] = splitQuery(path);
+  const pathnameWithoutLocale = localeMatcher
+    ? pathname.replace(localeMatcher, '')
+    : pathname;
+
+  return `/${locale}${pathnameWithoutLocale}${query}`;
+};
+
+const ANCHOR_OPEN_TAG = /<a\b[^>]*>/gi;
+const HREF_ATTRIBUTE = /(\shref\s*=\s*)(?:"([^"]*)"|'([^']*)')/i;
+
+/**
+ * Authored rich text (`text-block`) with every `<a href>` passed through
+ * `localize`. Its links reach the page as markup, not through `ThemeLink`, so
+ * `/kampanya/` in a paragraph on an English page would still open the Turkish
+ * site. A string rewrite rather than a DOM pass, because the markup is
+ * rendered on the server too, where there is no DOM. Only quoted `href`s on
+ * `<a>` tags are touched; everything else is returned byte for byte.
+ */
+export const localizeHtmlLinks = (
+  html: string,
+  localize: (href: string) => string
+): string => {
+  if (typeof html !== 'string' || !/<a\b/i.test(html)) return html;
+
+  return html.replace(ANCHOR_OPEN_TAG, (tag) =>
+    tag.replace(HREF_ATTRIBUTE, (attribute, prefix, doubled, single) => {
+      const href = doubled ?? single;
+      const localized = localize(href);
+      if (localized === href) return attribute;
+
+      const quote = doubled !== undefined ? '"' : "'";
+      return `${prefix}${quote}${localized}${quote}`;
+    })
+  );
+};