@akinon/pz-theme 2.0.162-beta.0 → 2.0.162

package/src/region/__tests__/region-contract.test.ts

@@ -0,0 +1,500 @@
+import fs from 'fs';
+import path from 'path';
+
+import {
+  emptyRegionRegistry,
+  isRegionRegistrableSlug,
+  isRegionReservedSlug,
+  isValidRegionCode,
+  isWritableRegionRegistry,
+  REGION_CONTENT_CAPABILITY,
+  REGION_DATA_SOURCES_ATTRIBUTE,
+  REGION_REGISTRY_ATTRIBUTE,
+  REGION_REGISTRY_SLUG,
+  REGION_REGISTRY_VERSION,
+  REGION_SLUG_INFIX,
+  regionFromLocale,
+  regionHasPlaceholder,
+  marketPlaceholderSlugs,
+  regionSlug,
+  readRegionDataSources,
+  readRegionRegistry,
+  serializeRegionRegistry
+} from '../region-contract';
+import type { RegionRegistry, RegionRegistryRead } from '../region-contract';
+
+/**
+ * ZERO-5391 — the contract both sides of per-country ("region") content read
+ * from: which country a locale belongs to, where a country's copy of an area
+ * lives, and how the `theme-regions` registry and a copy's own data-source
+ * records are parsed. The storefront and the editor must agree on every one of
+ * these, so the file is kept as two byte-identical copies and the last test
+ * compares them.
+ */
+
+const registryOf = (read: RegionRegistryRead): RegionRegistry => {
+  if (read.kind !== 'found') {
+    throw new Error(`expected a found registry, got ${JSON.stringify(read)}`);
+  }
+  return read.registry;
+};
+
+const SAMPLE = {
+  version: 1,
+  regions: {
+    ae: {
+      placeholders: {
+        header: { updatedAt: '2026-11-02T10:00:00.000Z' },
+        'theme-homepage-body': {}
+      }
+    }
+  }
+};
+
+describe('region contract — wire names', () => {
+  it('pins every name the storefront and the editor exchange', () => {
+    expect(REGION_SLUG_INFIX).toBe('-region-');
+    expect(REGION_REGISTRY_SLUG).toBe('theme-regions');
+    expect(REGION_REGISTRY_ATTRIBUTE).toBe('theme_regions');
+    expect(REGION_REGISTRY_VERSION).toBe(1);
+    expect(REGION_CONTENT_CAPABILITY).toBe('region-content');
+    expect(REGION_DATA_SOURCES_ATTRIBUTE).toBe('theme_region_dataSources');
+  });
+});
+
+describe('regionFromLocale', () => {
+  it.each([
+    ['en-ae', 'ae'],
+    ['ar-ae', 'ae'],
+    ['AR-AE', 'ae'],
+    [' en-ae ', 'ae'],
+    ['en-us', 'us'],
+    ['zh-hant-tw', 'tw']
+  ])('reads the country of %p as %p', (locale: string, region: string) => {
+    expect(regionFromLocale(locale)).toBe(region);
+  });
+
+  it.each([['en'], ['tr'], ['zh-hant'], ['es-419'], ['en-'], ['']])(
+    'gives no region for %p',
+    (locale: string) => {
+      expect(regionFromLocale(locale)).toBe('');
+    }
+  );
+
+  it.each([[undefined], [null], [42], [{ value: 'en-ae' }]])(
+    'gives no region for the non-string %p',
+    (locale: unknown) => {
+      expect(regionFromLocale(locale)).toBe('');
+    }
+  );
+});
+
+describe('isValidRegionCode', () => {
+  it('accepts two lowercase letters', () => {
+    expect(isValidRegionCode('ae')).toBe(true);
+    expect(isValidRegionCode('tr')).toBe(true);
+  });
+
+  it.each([
+    ['AE'],
+    ['uae'],
+    ['a1'],
+    ['__proto__'],
+    ['a'],
+    [''],
+    [undefined],
+    [7]
+  ])('rejects %p', (code: unknown) => {
+    expect(isValidRegionCode(code)).toBe(false);
+  });
+});
+
+describe('regionSlug', () => {
+  it('suffixes the canonical slug with the region', () => {
+    expect(regionSlug('header', 'ae')).toBe('header-region-ae');
+    expect(regionSlug('page-faq', 'sa')).toBe('page-faq-region-sa');
+  });
+
+  it('composes with a preview suffix outermost', () => {
+    expect(`${regionSlug('header', 'ae')}-preview-draft`).toBe(
+      'header-region-ae-preview-draft'
+    );
+  });
+});
+
+describe('isRegionReservedSlug', () => {
+  it('reserves every slug carrying the infix', () => {
+    expect(isRegionReservedSlug(regionSlug('header', 'ae'))).toBe(true);
+    expect(isRegionReservedSlug('page-super-region-deals')).toBe(true);
+  });
+
+  it('leaves slugs without the full infix alone', () => {
+    expect(isRegionReservedSlug('header')).toBe(false);
+    expect(isRegionReservedSlug('superregion')).toBe(false);
+    expect(isRegionReservedSlug('header-regions')).toBe(false);
+  });
+
+  it('sees a custom page through its placeholder slug', () => {
+    // The page slug passes; the placeholder `page-<slug>` does not, which is
+    // why custom page slugs are validated as `page-${slug}`.
+    expect(isRegionReservedSlug('region-days')).toBe(false);
+    expect(isRegionReservedSlug('page-region-days')).toBe(true);
+  });
+});
+
+describe('isRegionRegistrableSlug', () => {
+  const REGISTRABLE = [
+    'header',
+    'footer',
+    'theme-homepage-body',
+    'page-faq',
+    'modal-1a2b3c',
+    'server-error-body',
+    '0-leading-digit'
+  ];
+  const UNREGISTRABLE = [
+    'page-region-days',
+    'header-region-ae',
+    'promo_bar',
+    'Header',
+    '-header',
+    'page faq',
+    '',
+    '__proto__'
+  ];
+
+  it.each(REGISTRABLE.map((slug: string) => [slug]))(
+    'accepts %p',
+    (slug: string) => {
+      expect(isRegionRegistrableSlug(slug)).toBe(true);
+    }
+  );
+
+  it.each(UNREGISTRABLE.map((slug: string) => [slug]))(
+    'refuses %p',
+    (slug: string) => {
+      expect(isRegionRegistrableSlug(slug)).toBe(false);
+    }
+  );
+
+  it.each([[undefined], [null], [42], [['header']]])(
+    'refuses the non-string %p',
+    (slug: unknown) => {
+      expect(isRegionRegistrableSlug(slug)).toBe(false);
+    }
+  );
+
+  it('accepts exactly the slugs a registry read keeps', () => {
+    const all = [...REGISTRABLE, ...UNREGISTRABLE];
+    // Own keys, `__proto__` included (an assignment would set the prototype
+    // instead), serialised the way the widget stores them.
+    const placeholders = Object.fromEntries(
+      all.map((slug: string) => [slug, {}])
+    );
+    const registry = registryOf(
+      readRegionRegistry(
+        JSON.stringify({ version: 1, regions: { ae: { placeholders } } })
+      )
+    );
+
+    for (const slug of all) {
+      expect([slug, regionHasPlaceholder(registry, 'ae', slug)]).toEqual([
+        slug,
+        isRegionRegistrableSlug(slug)
+      ]);
+    }
+  });
+});
+
+describe('readRegionRegistry', () => {
+  it.each([[undefined], [null], [''], [{ value: '' }], [{ value: null }]])(
+    'reads %p as absent',
+    (raw: unknown) => {
+      expect(readRegionRegistry(raw)).toEqual({ kind: 'absent' });
+    }
+  );
+
+  it('reads a JSON string', () => {
+    expect(readRegionRegistry(JSON.stringify(SAMPLE))).toEqual({
+      kind: 'found',
+      registry: SAMPLE
+    });
+  });
+
+  it('reads the commerce {value, kwargs} wrapping', () => {
+    expect(
+      readRegionRegistry({ value: JSON.stringify(SAMPLE), kwargs: {} })
+    ).toEqual({ kind: 'found', registry: SAMPLE });
+    expect(readRegionRegistry({ value: SAMPLE, kwargs: {} })).toEqual({
+      kind: 'found',
+      registry: SAMPLE
+    });
+  });
+
+  it('reads an already parsed object without keeping a reference to it', () => {
+    const read = readRegionRegistry(SAMPLE);
+
+    expect(read).toEqual({ kind: 'found', registry: SAMPLE });
+    expect(registryOf(read)).not.toBe(SAMPLE);
+    expect(registryOf(read).regions.ae).not.toBe(SAMPLE.regions.ae);
+  });
+
+  it('reads malformed JSON as unreadable', () => {
+    expect(readRegionRegistry('{nope')).toEqual({
+      kind: 'unreadable',
+      reason: 'malformed-json'
+    });
+  });
+
+  it.each([['[]'], ['"text"'], [42], [true]])(
+    'reads the non-object %p as unreadable',
+    (raw: unknown) => {
+      expect(readRegionRegistry(raw)).toEqual({
+        kind: 'unreadable',
+        reason: 'not-an-object'
+      });
+    }
+  );
+
+  it.each([
+    [{ regions: {} }],
+    [{ version: 0, regions: {} }],
+    [{ version: '1', regions: {} }],
+    [{ version: NaN, regions: {} }]
+  ])('reads %p as a bad version', (raw: unknown) => {
+    expect(readRegionRegistry(raw)).toEqual({
+      kind: 'unreadable',
+      reason: 'bad-version'
+    });
+  });
+
+  it.each([
+    [{ version: 1 }],
+    [{ version: 1, regions: null }],
+    [{ version: 1, regions: [] }],
+    [{ version: 1, regions: 'ae' }]
+  ])('reads %p as having no regions', (raw: unknown) => {
+    expect(readRegionRegistry(raw)).toEqual({
+      kind: 'unreadable',
+      reason: 'no-regions'
+    });
+  });
+
+  it('drops invalid codes and slugs while keeping their siblings', () => {
+    const raw = JSON.stringify({
+      version: 1,
+      regions: {
+        ae: {
+          placeholders: {
+            header: {},
+            Header: {},
+            'header-region-ae': {},
+            ['__proto__']: {},
+            footer: {}
+          }
+        },
+        AE: { placeholders: { header: {} } },
+        uae: { placeholders: { header: {} } },
+        ['__proto__']: { placeholders: { header: {} } },
+        sa: { placeholders: { 'page-faq': {} } },
+        tr: 'not-an-entry',
+        us: { placeholders: ['header'] },
+        de: {}
+      }
+    });
+    const registry = registryOf(readRegionRegistry(raw));
+
+    expect(registry).toEqual({
+      version: 1,
+      regions: {
+        ae: { placeholders: { header: {}, footer: {} } },
+        sa: { placeholders: { 'page-faq': {} } }
+      }
+    });
+    expect(Object.getPrototypeOf(registry.regions)).toBe(Object.prototype);
+    expect(Object.getPrototypeOf(registry.regions.ae.placeholders)).toBe(
+      Object.prototype
+    );
+  });
+
+  it('keeps updatedAt only when it is a string, and drops other entry keys', () => {
+    const registry = registryOf(
+      readRegionRegistry({
+        version: 1,
+        regions: {
+          ae: {
+            placeholders: {
+              header: { updatedAt: '2026-11-02T10:00:00.000Z', live: true },
+              footer: { updatedAt: 1762077600000 },
+              'page-faq': { updatedAt: null },
+              'modal-1a2b3c': 'not-an-object'
+            }
+          }
+        }
+      })
+    );
+
+    expect(registry.regions.ae.placeholders).toEqual({
+      header: { updatedAt: '2026-11-02T10:00:00.000Z' },
+      footer: {},
+      'page-faq': {},
+      'modal-1a2b3c': {}
+    });
+  });
+
+  it('reads a later version that only added keys', () => {
+    const read = readRegionRegistry(
+      JSON.stringify({
+        version: 2,
+        drafts: { ae: { placeholders: { footer: {} } } },
+        regions: {
+          ae: {
+            placeholders: { header: { updatedAt: 'x', live: false } },
+            locales: ['en-ae']
+          }
+        }
+      })
+    );
+
+    expect(read).toEqual({
+      kind: 'found',
+      registry: {
+        version: 2,
+        regions: { ae: { placeholders: { header: { updatedAt: 'x' } } } }
+      }
+    });
+  });
+});
+
+describe('regionHasPlaceholder and marketPlaceholderSlugs', () => {
+  const registry = registryOf(readRegionRegistry(SAMPLE));
+
+  it('list the placeholders a region has its own copy of', () => {
+    expect(marketPlaceholderSlugs(registry, 'ae')).toEqual([
+      'header',
+      'theme-homepage-body'
+    ]);
+    expect(regionHasPlaceholder(registry, 'ae', 'header')).toBe(true);
+    expect(regionHasPlaceholder(registry, 'ae', 'footer')).toBe(false);
+    expect(marketPlaceholderSlugs(registry, 'sa')).toEqual([]);
+    expect(regionHasPlaceholder(registry, 'sa', 'header')).toBe(false);
+  });
+
+  it('use own properties only', () => {
+    for (const key of ['constructor', 'toString', '__proto__']) {
+      expect(marketPlaceholderSlugs(registry, key)).toEqual([]);
+      expect(regionHasPlaceholder(registry, key, 'header')).toBe(false);
+      expect(regionHasPlaceholder(registry, 'ae', key)).toBe(false);
+    }
+  });
+});
+
+describe('isWritableRegionRegistry and serializeRegionRegistry', () => {
+  it('writes only registries of this version or older', () => {
+    expect(isWritableRegionRegistry(emptyRegionRegistry())).toBe(true);
+    expect(isWritableRegionRegistry({ version: 1, regions: {} })).toBe(true);
+    expect(isWritableRegionRegistry({ version: 2, regions: {} })).toBe(false);
+  });
+
+  it('stamps the current version, which is why a later one must not be written', () => {
+    expect(
+      JSON.parse(serializeRegionRegistry({ version: 2, regions: {} })).version
+    ).toBe(REGION_REGISTRY_VERSION);
+  });
+
+  it('serialises the empty registry', () => {
+    expect(serializeRegionRegistry(emptyRegionRegistry())).toBe(
+      '{"version":1,"regions":{}}'
+    );
+  });
+
+  it('round-trips through readRegionRegistry', () => {
+    const registry = registryOf(readRegionRegistry(SAMPLE));
+    const serialized = serializeRegionRegistry(registry);
+
+    expect(readRegionRegistry(serialized)).toEqual({ kind: 'found', registry });
+    expect(readRegionRegistry({ value: serialized, kwargs: {} })).toEqual({
+      kind: 'found',
+      registry
+    });
+  });
+});
+
+describe('readRegionDataSources', () => {
+  const RECORDS = [
+    { id: 'ds-9', name: 'Bestsellers (AE)', region: 'ae' },
+    { id: 'ds-10', name: 'New in (AE)', region: 'ae' }
+  ];
+
+  it('reads a JSON string', () => {
+    expect(readRegionDataSources(JSON.stringify(RECORDS))).toEqual(RECORDS);
+  });
+
+  it('reads the commerce {value, kwargs} wrapping', () => {
+    expect(
+      readRegionDataSources({ value: JSON.stringify(RECORDS), kwargs: {} })
+    ).toEqual(RECORDS);
+    expect(readRegionDataSources({ value: RECORDS, kwargs: {} })).toEqual(
+      RECORDS
+    );
+  });
+
+  it('reads an already parsed array into a new array', () => {
+    const read = readRegionDataSources(RECORDS);
+
+    expect(read).toEqual(RECORDS);
+    expect(read).not.toBe(RECORDS);
+  });
+
+  it('returns the elements unvalidated', () => {
+    expect(readRegionDataSources('[1,null,"x",{"id":"ds-1"}]')).toEqual([
+      1,
+      null,
+      'x',
+      { id: 'ds-1' }
+    ]);
+    expect(readRegionDataSources('[]')).toEqual([]);
+  });
+
+  it.each([
+    [undefined],
+    [null],
+    [''],
+    ['{nope'],
+    ['{}'],
+    ['"text"'],
+    ['null'],
+    [42],
+    [true],
+    [{}],
+    [{ id: 'ds-1' }],
+    [{ value: null }],
+    [{ value: '{nope' }],
+    [{ value: { id: 'ds-1' } }]
+  ])('reads %p as no records', (raw: unknown) => {
+    expect(readRegionDataSources(raw)).toEqual([]);
+  });
+});
+
+describe('region contract — the editor copy', () => {
+  const SOURCE = path.resolve(__dirname, '../region-contract.ts');
+  // Sibling checkouts: this machine's name for the editor first, then the
+  // name a default clone of its repository gets.
+  const EDITOR = [
+    '../../../../../../pz-dynamic-widget/src/services/region/region-contract.ts',
+    '../../../../../../pz-theme-editor/src/services/region/region-contract.ts'
+  ]
+    .map((relative: string) => path.resolve(__dirname, relative))
+    .find((candidate: string) => fs.existsSync(candidate));
+
+  // Skipped, not failed, where the editor is not checked out beside pz-next
+  // (CI builds this repo alone). The reads stay inside it() so a missing file
+  // can never fail the collection of the tests above.
+  (EDITOR ? it : it.skip)('is byte-identical to this copy', () => {
+    const storefront = fs.readFileSync(SOURCE);
+    const editor = fs.readFileSync(EDITOR as string);
+
+    expect(editor.toString('utf8')).toBe(storefront.toString('utf8'));
+    expect(editor.equals(storefront)).toBe(true);
+  });
+});