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

package/src/custom/__tests__/use-theme-setting.test.tsx

@@ -231,6 +231,107 @@ describe('useThemeSetting — used outside a custom block', () => {
   });
 });
 
+/**
+ * A `text` default written per language: the author's own copy follows the
+ * page's language, while the editor keeps seeing one plain string. Turkish is
+ * the hidden default and English lives under /en, which is zsa-zsa-zsu's setup.
+ */
+describe('useThemeSetting — a text default written per language', () => {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const hooks = require('@akinon/next/hooks');
+  let localizationSpy: jest.SpyInstance;
+
+  const onPage = (locale: string) => {
+    const original = hooks.useLocalization;
+    localizationSpy = jest
+      .spyOn(hooks, 'useLocalization')
+      .mockImplementation(() => ({
+        ...original(),
+        locale,
+        defaultLocaleValue: 'tr',
+        locales: [{ value: 'tr' }, { value: 'en' }]
+      }));
+  };
+
+  afterEach(() => localizationSpy?.mockRestore());
+
+  const LABEL = { tr: 'MENÜ', en: 'MENU' };
+
+  const read = (
+    value: CustomBlockContextValue | null,
+    fallback: unknown = LABEL
+  ) =>
+    renderHook(
+      () =>
+        useThemeSetting('menuLabel', {
+          type: 'text',
+          label: 'Menu label',
+          default: fallback as Record<string, string>
+        }),
+      { wrapper: wrapperFor(value) }
+    ).result.current;
+
+  it('reads the entry for the page’s language when nothing is stored', () => {
+    onPage('en');
+    expect(read(contextValue())).toBe('MENU');
+
+    localizationSpy.mockRestore();
+    onPage('tr');
+    expect(read(contextValue())).toBe('MENÜ');
+  });
+
+  it('translates the default the editor seeded when the block was placed', () => {
+    onPage('en');
+    const seeded = contextValue({
+      properties: { menuLabel: { desktop: 'MENÜ' } }
+    });
+
+    expect(read(seeded)).toBe('MENU');
+  });
+
+  it('shows the merchant’s own text as typed, in every language', () => {
+    onPage('en');
+    const typed = contextValue({
+      properties: { menuLabel: { desktop: 'Kategoriler' } }
+    });
+
+    expect(read(typed)).toBe('Kategoriler');
+  });
+
+  it('tells the editor the default language’s text, as one plain string', () => {
+    onPage('en');
+    const sink = jest.fn();
+    read(contextValue({ sink }));
+
+    expect(sink.mock.calls[0][0]).toMatchObject({
+      key: 'menuLabel',
+      type: 'text',
+      defaultValue: { desktop: 'MENÜ' }
+    });
+  });
+
+  it('falls back to the default language for a language the author skipped', () => {
+    onPage('en');
+    expect(read(contextValue(), { tr: 'Tümü' })).toBe('Tümü');
+  });
+
+  it('reads the page’s entry outside a custom block too', () => {
+    onPage('en');
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    expect(read(null)).toBe('MENU');
+
+    warn.mockRestore();
+  });
+
+  it('leaves a one-string default exactly as it was', () => {
+    onPage('en');
+    expect(read(contextValue(), 'MENÜ')).toBe('MENÜ');
+  });
+});
+
 describe('useThemeSetting — invalid declarations throw in development', () => {
   const renderWith = (key: string, options: Record<string, unknown>) =>
     renderHook(

package/src/custom/index.ts

@@ -137,6 +137,22 @@ export type {
   ThemeSettingOptions
 } from './use-theme-setting';
 
+/**
+ * LINKS AND THE PAGE'S LOCALE. Storefront paths are stored and authored
+ * without one ('/yatak-odasi/'), which on an English page is the Turkish site.
+ * The `<a>` that `ThemeEditable` wraps gets the locale on its own. For any
+ * other link use `ThemeLink` in place of `next/link`, and for a bare string — a
+ * plain `<a>`, `router.push`, an address read off commerce data — run it
+ * through the function `useLocalizeHref()` returns. Nothing else in a block has
+ * to know which language the page is in.
+ *
+ * This entry, not the package root: the root re-exports `ThemePlaceholder`,
+ * which is server-only, so a client component importing from there fails the
+ * build.
+ */
+export { ThemeLink } from '../components/theme-link';
+export { useLocalizeHref } from '../hooks/use-localize-href';
+
 /**
  * The context every custom unit renders inside, for the one question the
  * components above cannot answer for a developer: is this the editor canvas?

package/src/custom/theme-editable.tsx

@@ -2,8 +2,10 @@
 
 import React from 'react';
 
+import { useLocalizeHref } from '../hooks/use-localize-href';
 import { getResponsiveValue } from '../utils';
 import { devWarn } from '../utils/dev-warn';
+import { useValueLocale } from '../utils/localized-value';
 import { partAttrs } from '../utils/part-styles';
 import { useCustomBlockContext } from './block-context';
 import type { CustomBlockContextValue } from './block-context';
@@ -113,6 +115,15 @@ export interface ThemeEditableProps {
   name: string;
   /** Overrides tag inference. The escape hatch for a container tag. */
   type?: EditableKind;
+  /**
+   * The authored text in the store's other languages, keyed by locale:
+   * `<ThemeEditable name="label" translations={{ en: 'MENU' }}><span>MENÜ</span>`.
+   * The child stays the default language's text, which is all the editor is
+   * told. Shown for as long as the field still says that text, including the
+   * copy the editor seeds when the block is placed. Text the merchant typed is
+   * theirs and shows as typed. Text and link labels only.
+   */
+  translations?: Readonly<Record<string, string>>;
   children?: React.ReactNode;
 }
 
@@ -148,13 +159,20 @@ export interface ThemeEditableProps {
 export function ThemeEditable({
   name,
   type,
+  translations,
   children
 }: ThemeEditableProps): React.ReactElement {
   const context = useCustomBlockContext();
-
-  // Untouched rather than empty, so a `<ThemeEditable>` copy-pasted into a
-  // plain component keeps rendering what the developer wrote while the warning
-  // tells them why nothing is editable.
+  const localizeHref = useLocalizeHref();
+  const valueLocale = useValueLocale();
+
+  // Untouched rather than empty, so a `<ThemeEditable>` copy-pasted outside a
+  // custom block keeps rendering what the developer wrote while the warning
+  // tells them why nothing is editable. What it does need is a Next app router
+  // page and the `LocalizationProvider` around it: the two hooks above reach
+  // `@akinon/next`'s `useLocalization`, which calls `next/navigation`'s
+  // `useRouter`. A test gets there with a mocked `@akinon/next/hooks`, the way
+  // this package's jest config does.
   if (!context) {
     devWarn(
       'ThemeEditable',
@@ -314,6 +332,25 @@ export function ThemeEditable({
     )
   };
 
+  // The author's own text, still untouched, in the page's language. Compared
+  // with the authored child rather than "nothing stored" because the editor
+  // stores that child as the value when the block is placed: a trigger placed
+  // on a Turkish store carries `label: { desktop: 'MENÜ' }` from day one.
+  const translated =
+    valueProp === 'children' &&
+    valueLocale.locale &&
+    valueLocale.locale !== valueLocale.defaultLocale
+      ? translations?.[valueLocale.locale]
+      : undefined;
+
+  if (
+    typeof translated === 'string' &&
+    translated !== '' &&
+    nextProps[valueProp] === authoredValue
+  ) {
+    nextProps[valueProp] = translated;
+  }
+
   if (hrefKey) {
     // A destination is a plain string in every control that writes one, so it
     // never carries the picker's `{ url }` wrapper.
@@ -325,6 +362,22 @@ export function ThemeEditable({
     );
   }
 
+  // The page's locale goes on the destination here, once, for every custom
+  // block and section. The stored address and the authored JSX both say
+  // '/yatak-odasi/', which on an English page is the Turkish site, and a
+  // developer who had to remember `/en` on each link would forget one. Only a
+  // root-relative href changes (see `localizeHref`); the stored value is left
+  // alone, because the editor reads properties, never the rendered anchor.
+  const destination = hrefKey
+    ? nextProps.href
+    : tag === 'a'
+      ? childProps.href
+      : undefined;
+
+  if (typeof destination === 'string') {
+    nextProps.href = localizeHref(destination);
+  }
+
   if (stampsFieldPart) {
     // `use-designer-features.tsx` resolves the nearest `[data-part]` under the
     // click and ships its value as `partName` on SELECT_BLOCK, so this one

package/src/custom/use-theme-setting.ts

@@ -2,6 +2,12 @@
 
 import { getResponsiveValue } from '../utils';
 import { devWarn } from '../utils/dev-warn';
+import {
+  isLocalizedValue,
+  resolveLocalizedValue,
+  useValueLocale
+} from '../utils/localized-value';
+import type { ValueLocale } from '../utils/localized-value';
 import { useCustomBlockContext } from './block-context';
 import {
   normalizeSettingChoices,
@@ -52,13 +58,22 @@ interface SettingValueByType {
  */
 type NoInferred<T> = [T][T extends unknown ? 0 : never];
 
+/**
+ * A `text` default may be written per language — `{ tr: 'MENÜ', en: 'MENU' }`
+ * — and the hook still returns one string: the entry for the page's locale.
+ * See `splitDefault`.
+ */
+type DefaultFor<TType, TValue> = TType extends 'text'
+  ? NoInferred<TValue> | Readonly<Record<string, string>>
+  : NoInferred<TValue>;
+
 export interface ThemeSettingOptions<
   TType extends PropertyType = PropertyType,
   TValue = unknown
 > {
   type: TType;
   label: string;
-  default?: NoInferred<TValue>;
+  default?: DefaultFor<TType, TValue>;
   options?: ReadonlyArray<ThemeSettingChoice>;
   min?: number;
   max?: number;
@@ -156,6 +171,41 @@ const resolveAuthoredDefault = (
   return resolved === NOT_AUTHORED ? value : resolved;
 };
 
+/**
+ * A `text` default written per language, split into its two readings.
+ *
+ * `base` is the default language's entry. It is what the editor is told the
+ * default is, so the panel, the seed a newly placed block is stored with and
+ * the static `settings` declaration all keep the plain string they always had,
+ * and a catalog declaring one is accepted by an editor that has never heard of
+ * languages. `page` is the entry for the locale being shown.
+ *
+ * Any other default, and a `text` default written as one string, reads the
+ * same both ways.
+ */
+const splitDefault = (
+  declaration: ThemeSettingOptions<PropertyType, unknown>,
+  valueLocale: ValueLocale
+): { base: unknown; page: unknown; perLocale: boolean } => {
+  const value = declaration.default;
+
+  if (
+    declaration.type !== 'text' ||
+    !isLocalizedValue(value, valueLocale.locales)
+  ) {
+    return { base: value, page: value, perLocale: false };
+  }
+
+  return {
+    base: resolveLocalizedValue(value, {
+      ...valueLocale,
+      locale: valueLocale.defaultLocale
+    }),
+    page: resolveLocalizedValue(value, valueLocale),
+    perLocale: true
+  };
+};
+
 /**
  * Declares one merchant-editable value that has no on-screen representation —
  * how many products a grid shows, which category it pulls from, whether a
@@ -181,13 +231,21 @@ export function useThemeSetting<
   TValue = SettingValueByType[TType]
 >(key: string, options: ThemeSettingOptions<TType, TValue>): TValue {
   const context = useCustomBlockContext();
+  const valueLocale = useValueLocale();
   const declaration = options as ThemeSettingOptions<PropertyType, unknown>;
 
   assertDeclarationIsValid(key, declaration);
 
+  const defaults = splitDefault(declaration, valueLocale);
+
   if (!context) {
-    // Never throws: a developer previewing the component in a plain React tree,
-    // a storybook or a unit test should see the declared defaults, not a crash.
+    // A missing block context is never an error on its own: a developer
+    // previewing the component in a storybook or a unit test should see the
+    // declared defaults, not a crash. The tree around it is not free of
+    // requirements, though — `useValueLocale` above reads `@akinon/next`'s
+    // `useLocalization`, which calls `next/navigation`'s `useRouter` — so the
+    // render still needs a Next app router and the `LocalizationProvider`, or
+    // a mocked `@akinon/next/hooks` the way this package's jest config does.
     // The key rides in the message so distinct misplacements dedupe
     // independently inside `devWarn`.
     devWarn(
@@ -196,13 +254,15 @@ export function useThemeSetting<
         `unreachable and the declared default is used instead. Render this ` +
         `component through a block registered with registerCustomBlocks().`
     );
-    return declaration.default as TValue;
+    return defaults.page as TValue;
   }
 
   // Reported on every render rather than once from an effect: the collection
   // pass renders the component and reads the sink synchronously, and on the
   // server effects never run at all.
-  context.collect?.setting(buildDescriptor(key, declaration));
+  context.collect?.setting(
+    buildDescriptor(key, { ...declaration, default: defaults.base })
+  );
 
   const breakpoint = context.currentBreakpoint;
 
@@ -219,9 +279,16 @@ export function useThemeSetting<
   // undefined.
   const resolved = getResponsiveValue(stored, breakpoint, NOT_AUTHORED);
 
-  return (
-    resolved === NOT_AUTHORED
-      ? resolveAuthoredDefault(declaration.default, breakpoint)
-      : resolved
-  ) as TValue;
+  if (resolved === NOT_AUTHORED) {
+    return resolveAuthoredDefault(defaults.page, breakpoint) as TValue;
+  }
+
+  // The default-language text as the editor seeded it when the block was
+  // placed, never changed since: still the author's copy, so it follows the
+  // page's language. Anything the merchant typed is theirs and shows as typed.
+  if (defaults.perLocale && resolved === defaults.base) {
+    return defaults.page as TValue;
+  }
+
+  return resolved as TValue;
 }

package/src/hooks/use-localize-href.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useLocalization } from '@akinon/next/hooks';
+import { urlLocaleMatcherRegex } from '@akinon/next/utils';
+import { localizeHref } from '../utils/localize-href';
+
+/**
+ * `localizeHref` bound to the active locale, for anything that navigates
+ * without a `ThemeLink`: `router.push`, a plain `<a>`, a fetched page URL.
+ *
+ * Everything that localizes goes through this hook rather than calling
+ * `localizeHref` itself, because this is the only place that knows the
+ * storefront's own address — and without it a merchant's full URL to this same
+ * site would not be recognized as a path. `NEXT_PUBLIC_URL` is a public env
+ * var, so Next inlines the same literal into the server render and the client
+ * bundle, and the two cannot disagree about which links are internal.
+ */
+export const useLocalizeHref = (): ((href: string) => string) => {
+  const { locale, defaultLocaleValue, localeUrlStrategy } = useLocalization();
+  const siteUrl = process.env.NEXT_PUBLIC_URL;
+
+  return useCallback(
+    (href: string) =>
+      localizeHref(href, {
+        locale,
+        defaultLocaleValue,
+        localeUrlStrategy,
+        localeMatcher: urlLocaleMatcherRegex,
+        siteUrl
+      }),
+    [locale, defaultLocaleValue, localeUrlStrategy, siteUrl]
+  );
+};

package/src/index.ts

@@ -27,6 +27,18 @@ export { isBrowseMode, useBrowseMode } from './browse-mode';
 
 export { WithDesignerFeatures } from './components/with-designer-features';
 
+// The locale rules as plain functions, for code that already has the store's
+// localization settings in hand. `ThemeLink` and `useLocalizeHref` are NOT
+// here: this entry re-exports `ThemePlaceholder`, which imports 'server-only',
+// so importing anything from it inside a client component fails the build. A
+// brand's custom section takes both from '@akinon/pz-theme/src/custom'.
+export {
+  isRootRelativeHref,
+  localizeHref,
+  localizeHtmlLinks
+} from './utils/localize-href';
+export type { HrefLocale } from './utils/localize-href';
+
 export type { Section } from './theme-section';
 export type { Block } from './theme-block';
 

package/src/sections/find-in-store-section.tsx

@@ -28,6 +28,7 @@ import {
   resolveThemeCssVariables
 } from '../utils';
 import { isNarrowBreakpoint } from '../utils/breakpoints';
+import { useLocalizeHref } from '../hooks/use-localize-href';
 
 import { postToEditor } from '../editor-bridge';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
@@ -534,6 +535,7 @@ export default function FindInStoreSection({
   selectedBlockId = null
 }: FindInStoreSectionProps) {
   const { t } = useLocalization();
+  const localize = useLocalizeHref();
   const themeSettings = useThemeSettingsContext();
 
   const [productUrlInput, setProductUrlInput] = useState('');
@@ -1462,7 +1464,7 @@ export default function FindInStoreSection({
                     )
                   ) : productUrl ? (
                     <a
-                      href={productUrl}
+                      href={localize(productUrl)}
                       className="text-[13px] font-semibold text-slate-800 underline underline-offset-4"
                     >
                       View product

package/src/sections/hover-showcase-section.tsx

@@ -2,6 +2,7 @@
 
 import React, { useState, useEffect } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
+import { useLocalizeHref } from '../hooks/use-localize-href';
 import ThemeBlock, { Block } from '../theme-block';
 import { useThemeSettingsContext } from '../theme-settings-context';
 import {
@@ -32,6 +33,9 @@ const HoverShowcaseSection: React.FC<HoverShowcaseSectionProps> = ({
   selectedBlockId = null
 }) => {
   const { locale } = useLocalization();
+  // The section draws its items itself (never through the item block), so
+  // their plain anchors need the active locale added here.
+  const localize = useLocalizeHref();
   const defaultLocale = process.env.NEXT_PUBLIC_DEFAULT_LOCALE || 'en';
   const themeSettings = useThemeSettingsContext();
 
@@ -229,7 +233,7 @@ const HoverShowcaseSection: React.FC<HoverShowcaseSectionProps> = ({
                   onClick={() => setActiveIndex(index)}
                 >
                   {link ? (
-                    <a href={link} className="decoration-none">
+                    <a href={localize(link)} className="decoration-none">
                       <h3
                         style={{
                           fontSize: String(titleFontSize),
@@ -378,7 +382,7 @@ const HoverShowcaseSection: React.FC<HoverShowcaseSectionProps> = ({
                     onMouseEnter={() => setActiveIndex(index)}
                   >
                     {link ? (
-                      <a href={link} className="decoration-none">
+                      <a href={localize(link)} className="decoration-none">
                         <h3
                           style={{
                             fontSize: String(titleFontSize),

package/src/sections/installment-options-section.tsx

@@ -21,6 +21,7 @@ import {
   resolveThemeCssVariables
 } from '../utils';
 import { isNarrowBreakpoint } from '../utils/breakpoints';
+import { useLocalizeHref } from '../hooks/use-localize-href';
 
 import { postToEditor } from '../editor-bridge';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
@@ -416,6 +417,7 @@ export default function InstallmentOptionsSection({
 }: InstallmentOptionsSectionProps) {
   const themeSettings = useThemeSettingsContext();
   const { t } = useLocalization();
+  const localize = useLocalizeHref();
   const isMobile = isNarrowBreakpoint(currentBreakpoint);
 
   const maxWidth = getResponsiveValue(
@@ -833,7 +835,7 @@ export default function InstallmentOptionsSection({
                   </p>
                   {productUrl && productUrl !== '#' && (
                     <a
-                      href={productUrl}
+                      href={localize(productUrl)}
                       className="text-xs font-semibold text-[#0f172a] underline underline-offset-4"
                     >
                       View product

package/src/sections/slider-quick-view.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import React from 'react';
-import NextLink from 'next/link';
+import { ThemeLink as NextLink } from '../components/theme-link';
 
 import { partAttrs } from '../utils';
 import { useOverlay } from '../hooks/use-overlay';