@akinon/pz-theme 2.0.113-rc.0 → 2.0.113

package/CHANGELOG.md

@@ -1,40 +1,13 @@
 # @akinon/pz-theme
 
-## 2.0.113-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d45]
-- Updated dependencies [dca1281]
-  - @akinon/next@2.0.113-rc.0
-  - @akinon/theme-contract@2.0.113-rc.0
+## 2.0.113
+
+### Patch Changes
+
+- ca9e69e: Add `registerCustomPages([{ path, label }])` so a brand storefront announces its own composable pages (CMS flat pages behind pretty URLs, campaign landings) to the theme editor's page dropdown as the `customPages` field of `PLACEHOLDERS_AVAILABLE`, each with the `page-<slug>` placeholder it composes on. The list belongs to the brand build rather than the editor, which serves every tenant.
+- ca9e69e: ZERO-5088: implement custom page catalog management
+  - @akinon/next@2.0.113
+  - @akinon/theme-contract@2.0.113
 
 ## 2.0.112
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.113-rc.0",
+  "version": "2.0.113",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.113-rc.0",
+    "@akinon/next": "2.0.113",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.113-rc.0",
+    "@akinon/theme-contract": "2.0.113",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.113-rc.0",
+    "@akinon/next": "2.0.113",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/custom-catalog-announce.test.ts

@@ -127,6 +127,46 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     ]);
   });
 
+  it('carries the brand page list ungated, as a third sibling field', () => {
+    // No designer flag: the page list is route paths and page names, the same
+    // class of fact as the placeholder slugs, so it rides every frame — a brand
+    // that registers pages and nothing else still gets them listed on a
+    // document whose only frame went out before the designer flag arrived.
+    const { registry, register } = load();
+
+    registry.registerPlaceholder('header');
+    register.registerCustomPages([
+      { path: '/hakkimizda', label: 'Hakkımızda' }
+    ]);
+    jest.advanceTimersByTime(100);
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const [payload] = frames();
+    expect(payload.placeholders).toEqual(['header']);
+    expect(payload.customPages).toEqual({
+      pages: [
+        {
+          path: '/hakkimizda',
+          label: 'Hakkımızda',
+          placeholder: 'page-hakkimizda'
+        }
+      ]
+    });
+    // The two gated catalogs stay withheld from an unproven frame.
+    expect('customBlocks' in payload).toBe(false);
+    expect('customSections' in payload).toBe(false);
+  });
+
+  it('posts no page field at all for a build that registers no pages', () => {
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    const [payload] = frames();
+    expect('customPages' in payload).toBe(false);
+  });
+
   it('carries the section catalog as a SIBLING field, not inside the block one', () => {
     (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
       true;

package/src/custom/__tests__/register-custom-pages.test.ts

@@ -0,0 +1,77 @@
+import { getCustomPageCatalog, resetCustomPageCatalog } from '../page-catalog';
+import { CUSTOM_PAGE_LIMITS } from '../page-types';
+import { registerCustomPages } from '../register';
+
+/**
+ * The brand page list a storefront announces to the editor's page dropdown.
+ * The list is the brand's to declare — the editor serves every tenant, so a
+ * page written into its static registry showed up in every brand's dropdown
+ * (GANT's flat pages in a ZsaZsaZsu editor). Registration validates the whole
+ * list before it mutates anything, and materializes the placeholder each page
+ * composes on so the two repos cannot derive it differently.
+ */
+describe('registerCustomPages', () => {
+  afterEach(() => {
+    resetCustomPageCatalog();
+  });
+
+  it('announces nothing until a page is registered', () => {
+    expect(getCustomPageCatalog()).toBeNull();
+  });
+
+  it('announces each page with the page-<slug> placeholder it composes on', () => {
+    registerCustomPages([
+      { path: '/hakkimizda', label: ' Hakkımızda ' },
+      { path: '/q/class-of-gant', label: 'Class Of GANT' }
+    ]);
+
+    expect(getCustomPageCatalog()).toEqual({
+      pages: [
+        { path: '/hakkimizda', label: 'Hakkımızda', placeholder: 'page-hakkimizda' },
+        {
+          path: '/q/class-of-gant',
+          label: 'Class Of GANT',
+          placeholder: 'page-q-class-of-gant'
+        }
+      ]
+    });
+  });
+
+  it('refuses a path with a trailing slash, query, uppercase or locale prefix', () => {
+    for (const path of ['/hakkimizda/', '/hakkimizda?x=1', '/Hakkimizda', 'hakkimizda', '/tr/hakkimizda ']) {
+      expect(() => registerCustomPages([{ path, label: 'X' }])).toThrow(
+        /not a lowercase \/segment path/
+      );
+    }
+    // Nothing registered from a call that failed validation.
+    expect(getCustomPageCatalog()).toBeNull();
+  });
+
+  it('refuses an empty label and a duplicate path, in one call or across calls', () => {
+    expect(() =>
+      registerCustomPages([{ path: '/hakkimizda', label: '   ' }])
+    ).toThrow(/label is empty/);
+
+    expect(() =>
+      registerCustomPages([
+        { path: '/hakkimizda', label: 'A' },
+        { path: '/hakkimizda', label: 'B' }
+      ])
+    ).toThrow(/appears twice/);
+
+    registerCustomPages([{ path: '/hakkimizda', label: 'A' }]);
+    expect(() =>
+      registerCustomPages([{ path: '/hakkimizda', label: 'B' }])
+    ).toThrow(/registered twice/);
+  });
+
+  it('refuses a list over the cap before registering any of it', () => {
+    const pages = Array.from(
+      { length: CUSTOM_PAGE_LIMITS.pagesPerBuild + 1 },
+      (_, index) => ({ path: `/page-${index}`, label: `Page ${index}` })
+    );
+
+    expect(() => registerCustomPages(pages)).toThrow(/over the 32 cap/);
+    expect(getCustomPageCatalog()).toBeNull();
+  });
+});

package/src/custom/index.ts

@@ -53,7 +53,11 @@ export type {
 
 export type { CustomPartDeclaration, CustomPartsDeclaration } from './parts';
 
-export { registerCustomBlocks, registerCustomSections } from './register';
+export {
+  registerCustomBlocks,
+  registerCustomPages,
+  registerCustomSections
+} from './register';
 
 /**
  * The SECTION authoring API.
@@ -182,6 +186,20 @@ export type {
   CustomSectionDescriptor
 } from './section-types';
 
+/**
+ * The brand PAGE list: `registerCustomPages([{ path, label }])` from the client
+ * root, announced beside the two catalogs so the editor's page dropdown lists a
+ * brand's own routes for that brand only. The caps and the path grammar are
+ * exported for the editor's mirror, like `CUSTOM_SECTION_LIMITS`.
+ */
+export { getCustomPageCatalog } from './page-catalog';
+export { CUSTOM_PAGE_LIMITS, CUSTOM_PAGE_PATH_PATTERN } from './page-types';
+export type {
+  CustomPageCatalog,
+  CustomPageDescriptor,
+  CustomPageInput
+} from './page-types';
+
 // The predicate, not the pattern. Every consumer that has to treat a
 // developer-authored type differently tests this one function, so the grammar
 // stays in types.ts and cannot be re-derived slightly wrong somewhere else.

package/src/custom/page-catalog.ts

@@ -0,0 +1,64 @@
+import { devWarn } from '../utils/dev-warn';
+import { CUSTOM_PAGE_LIMITS } from './page-types';
+import type { CustomPageCatalog, CustomPageDescriptor } from './page-types';
+
+/**
+ * The brand pages this build announces to the editor, keyed by path.
+ *
+ * Module state on the same terms as `catalog.ts` and `section-catalog.ts`: one
+ * Map per bundle, filled from the client root only, read by the announce in
+ * `placeholder-registry.ts`. Directive-free for the same reason those two are —
+ * the announcer calls `getCustomPageCatalog()` without a directive of its own.
+ */
+const pageCatalog = new Map<string, CustomPageDescriptor>();
+
+/** Adds a page, refusing rather than overwriting a path already announced. */
+export const addPageToCatalog = (descriptor: CustomPageDescriptor) => {
+  if (pageCatalog.has(descriptor.path)) {
+    throw new Error(
+      `[pz-theme] Brand page "${descriptor.path}" is registered twice in this build. ` +
+        `Register each path once — the second entry would replace the first in the editor's page list.`
+    );
+  }
+
+  if (pageCatalog.size >= CUSTOM_PAGE_LIMITS.pagesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build registers more than ${CUSTOM_PAGE_LIMITS.pagesPerBuild} brand pages. ` +
+        `The cap exists because the whole list is posted to the editor on every placeholder announce.`
+    );
+  }
+
+  pageCatalog.set(descriptor.path, descriptor);
+};
+
+export const getCustomPagePaths = (): string[] => Array.from(pageCatalog.keys());
+
+/**
+ * The payload the storefront announces. Null when nothing is registered, so
+ * the announcer omits the field rather than posting an empty list — a build
+ * with no brand pages must be indistinguishable from one built before the
+ * field existed.
+ */
+export const getCustomPageCatalog = (): CustomPageCatalog | null => {
+  if (pageCatalog.size === 0) return null;
+
+  const payload: CustomPageCatalog = {
+    pages: Array.from(pageCatalog.values())
+  };
+
+  const bytes = JSON.stringify(payload).length;
+  if (bytes > CUSTOM_PAGE_LIMITS.catalogBytes) {
+    devWarn(
+      'customPageCatalog',
+      `Brand page catalog is ${bytes} bytes, over the ${CUSTOM_PAGE_LIMITS.catalogBytes} byte cap. ` +
+        `The editor will reject it and this brand's pages will be missing from the page list; shorten the labels.`
+    );
+  }
+
+  return payload;
+};
+
+/** Test-only. Module state outlives a test file otherwise. */
+export const resetCustomPageCatalog = () => {
+  pageCatalog.clear();
+};

package/src/custom/page-types.ts

@@ -0,0 +1,91 @@
+/**
+ * Brand pages announced to the theme editor's page list.
+ *
+ * A brand storefront routes pages the reference app never had — CMS flat pages
+ * behind pretty URLs (`/gizlilik-politikasi`), campaign landings under a legacy
+ * prefix (`/q/class-of-gant`). Each composes on its own `page-<slug>`
+ * placeholder derived from the path (`customPageSlugFromPath`), and the editor
+ * lists it in the page dropdown so a designer can open and compose it.
+ *
+ * The LIST lives in the brand's build and rides the placeholder announce, not
+ * in the editor. The editor is one SPA serving every tenant: a page path
+ * written into its static registry appears in EVERY brand's dropdown, pointing
+ * at a route only one storefront can serve — which is exactly what happened
+ * with GANT's flat pages before this existed.
+ *
+ * The page catalog is the third sibling field on `PLACEHOLDERS_AVAILABLE`,
+ * beside `customBlocks` and `customSections`, and it is a sibling for the same
+ * reason those two are: the editor validates each field whole and drops it on
+ * an unexpected shape, so a malformed page list costs the page list only.
+ */
+
+export interface CustomPageInput {
+  /**
+   * The storefront path the editor opens, without locale or query:
+   * `/hakkimizda`, `/q/class-of-gant`. Lowercase ASCII segments, because the
+   * placeholder slug is derived from it and the slug grammar is exactly that.
+   */
+  path: string;
+  /** What the page dropdown shows for it, after the "Flat Page /" prefix. */
+  label: string;
+}
+
+/** What is announced: the input plus the placeholder the page composes on. */
+export interface CustomPageDescriptor {
+  path: string;
+  label: string;
+  /**
+   * `customPageSlugFromPath(path)`, materialized by the SENDER so the editor
+   * and the storefront cannot disagree on which slot a composition saves to.
+   * The editor still checks it is a `page-` slug: the family is what keeps a
+   * page from claiming a chrome placeholder.
+   */
+  placeholder: string;
+}
+
+export interface CustomPageCatalog {
+  pages: CustomPageDescriptor[];
+}
+
+/**
+ * Caps, mirrored LITERALLY in the editor (`config/pages/custom-page-catalog.ts`)
+ * for the reason `CUSTOM_SECTION_LIMITS` gives: the receiver drops the whole
+ * catalog when one is exceeded, so a number that moves on one side alone
+ * empties a brand's page list.
+ */
+export const CUSTOM_PAGE_LIMITS = {
+  pagesPerBuild: 32,
+  pathLength: 128,
+  labelLength: 64,
+  catalogBytes: 16 * 1024
+} as const;
+
+/**
+ * `/segment` or `/segment/segment`, each segment lowercase letters, digits and
+ * hyphens. No trailing slash, no query, no locale prefix — the editor prefixes
+ * the channel's base URL itself.
+ */
+export const CUSTOM_PAGE_PATH_PATTERN =
+  /^\/[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)*$/;
+
+/** Why a path is not a valid brand page path, or null when it is. */
+export const customPagePathError = (path: unknown): string | null => {
+  if (typeof path !== 'string') return 'the path is not a string';
+  if (path.length > CUSTOM_PAGE_LIMITS.pathLength) {
+    return `the path is longer than ${CUSTOM_PAGE_LIMITS.pathLength} characters`;
+  }
+  if (!CUSTOM_PAGE_PATH_PATTERN.test(path)) {
+    return `the path ${JSON.stringify(path)} is not a lowercase /segment path without a trailing slash`;
+  }
+  return null;
+};
+
+/** Why a label is not a valid brand page label, or null when it is. */
+export const customPageLabelError = (label: unknown): string | null => {
+  if (typeof label !== 'string') return 'the label is not a string';
+  if (label.trim().length === 0) return 'the label is empty';
+  if (label.length > CUSTOM_PAGE_LIMITS.labelLength) {
+    return `the label is longer than ${CUSTOM_PAGE_LIMITS.labelLength} characters`;
+  }
+  return null;
+};

package/src/custom/register.ts

@@ -70,6 +70,17 @@ import {
   partStateError
 } from './parts';
 import { slotNameError } from './slot-nodes';
+import { customPageSlugFromPath } from '../chrome/placeholder-slugs';
+import {
+  addPageToCatalog,
+  getCustomPagePaths
+} from './page-catalog';
+import {
+  CUSTOM_PAGE_LIMITS,
+  customPageLabelError,
+  customPagePathError
+} from './page-types';
+import type { CustomPageDescriptor, CustomPageInput } from './page-types';
 import type {
   CustomBlockDefinition,
   CustomBlockInput,
@@ -916,3 +927,86 @@ export const registerCustomSections = (
   // catalogs in one frame.
   announceCustomBlocks();
 };
+
+/**
+ * Registers the brand pages the editor lists in its page dropdown.
+ *
+ * A brand routes pages the reference app never had — CMS flat pages behind
+ * pretty URLs, campaign landings under a legacy prefix. Each composes on its own
+ * `page-<slug>` placeholder (`customPageSlugFromPath`), and the editor can only
+ * offer what it knows about: the list rides the placeholder announce as the
+ * `customPages` field, beside the block and section catalogs. The list belongs
+ * HERE and not in the editor because the editor serves every tenant — a path
+ * in its static registry shows up in every brand's dropdown.
+ *
+ * Import the barrel that calls this from the CLIENT ROOT ONLY, like the other
+ * two registrations. The whole list is validated before anything is mutated,
+ * so a bad entry fails the build with its path in the message rather than
+ * announcing half a list.
+ */
+export const registerCustomPages = (pages: CustomPageInput[]): void => {
+  if (!Array.isArray(pages)) {
+    throw new Error(
+      '[pz-theme] registerCustomPages() expects an array of { path, label } entries.'
+    );
+  }
+
+  const pending: CustomPageDescriptor[] = [];
+  const claimed = new Set<string>();
+
+  pages.forEach((entry, index) => {
+    if (!entry || typeof entry !== 'object') {
+      throw new Error(
+        `[pz-theme] registerCustomPages() entry #${index} is not a { path, label } object.`
+      );
+    }
+
+    const pathError = customPagePathError(entry.path);
+    if (pathError) {
+      throw new Error(
+        `[pz-theme] registerCustomPages() entry #${index}: ${pathError}. ` +
+          `Use the storefront path without locale, query or trailing slash, e.g. "/hakkimizda" or "/q/class-of-gant".`
+      );
+    }
+
+    const labelError = customPageLabelError(entry.label);
+    if (labelError) {
+      throw new Error(
+        `[pz-theme] registerCustomPages() entry ${JSON.stringify(entry.path)}: ${labelError}. ` +
+          `The label is what the editor's page dropdown shows.`
+      );
+    }
+
+    if (claimed.has(entry.path)) {
+      throw new Error(
+        `[pz-theme] Brand page "${entry.path}" appears twice in one registerCustomPages() call.`
+      );
+    }
+
+    claimed.add(entry.path);
+    pending.push({
+      path: entry.path,
+      label: entry.label.trim(),
+      // Materialized by the sender: the storefront mounts this slot for the
+      // page, and the editor saves compositions against what is announced, so
+      // the two cannot disagree on which slot a page composes on.
+      placeholder: customPageSlugFromPath(entry.path)
+    });
+  });
+
+  const total = getCustomPagePaths().length + pending.length;
+  if (total > CUSTOM_PAGE_LIMITS.pagesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build would register ${total} brand pages, over the ` +
+        `${CUSTOM_PAGE_LIMITS.pagesPerBuild} cap. The cap exists because the whole list is posted to ` +
+        `the editor on every placeholder announce.`
+    );
+  }
+
+  pending.forEach(addPageToCatalog);
+
+  // The same re-arm the two catalogs use: this runs at module evaluation, long
+  // before any placeholder has mounted, so it only schedules the announce that
+  // will eventually carry the slugs and the page list in one frame.
+  announceCustomBlocks();
+};

package/src/index.ts

@@ -216,6 +216,7 @@ export {
   defineCustomBlock,
   defineCustomSection,
   registerCustomBlocks,
+  registerCustomPages,
   registerCustomSections,
   ThemeEditable,
   ThemeRegion,
@@ -223,6 +224,9 @@ export {
   useThemeSetting,
   getCustomCatalog,
   getCustomSectionCatalog,
+  getCustomPageCatalog,
+  CUSTOM_PAGE_LIMITS,
+  CUSTOM_PAGE_PATH_PATTERN,
   isCustomThemeType,
   CUSTOM_TYPE_PREFIX,
   CUSTOM_SLOT_BLOCK_TYPE,
@@ -242,6 +246,9 @@ export type {
   CustomBlockInput,
   CustomBlockOptions,
   CustomCatalog,
+  CustomPageCatalog,
+  CustomPageDescriptor,
+  CustomPageInput,
   CustomPartDeclaration,
   CustomPartsDeclaration,
   CustomRegionDeclaration,

package/src/placeholder-registry.ts

@@ -1,5 +1,6 @@
 import { getCatalogVendor, getCustomCatalog } from './custom/catalog';
 import { getCustomSectionCatalog } from './custom/section-catalog';
+import { getCustomPageCatalog } from './custom/page-catalog';
 import {
   ACTION_CAPABILITIES,
   type ActionCapability
@@ -9,6 +10,7 @@ import {
   type StatePinCapability
 } from './state-pin-capabilities';
 import type { CustomSectionCatalog } from './custom/section-types';
+import type { CustomPageCatalog } from './custom/page-types';
 import type { CustomCatalog } from './custom/types';
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
 
@@ -60,6 +62,19 @@ interface PlaceholdersAvailablePayload {
    * with it.
    */
   customSections?: CustomSectionCatalog;
+  /**
+   * The brand pages the editor lists in its page dropdown, each with the
+   * `page-<slug>` placeholder it composes on. A third SIBLING field, on the
+   * same terms as the two above: validated whole and dropped whole by the
+   * receiver, so a malformed page list costs the page list only.
+   *
+   * NOT behind the designer gate below. The list is route paths and page
+   * names — public URLs, the same class of fact as the placeholder slugs —
+   * so there is nothing to withhold, and riding every frame means a brand
+   * that registers pages and nothing else still gets them listed on a
+   * document whose only frame went out before the designer flag arrived.
+   */
+  customPages?: CustomPageCatalog;
 
   /**
    * Which kinds of state pin THIS build can perform, so the editor can offer
@@ -135,6 +150,11 @@ const flush = () => {
     actionCapabilities: ACTION_CAPABILITIES
   };
 
+  // Omitted entirely when nothing is registered: a build with no brand pages
+  // must look exactly like one built before the field existed.
+  const customPages = getCustomPageCatalog();
+  if (customPages) data.customPages = customPages;
+
   // Being framed is NOT enough to hand the catalog over. A storefront is
   // legitimately framed in production — payment providers, marketplace
   // previews — and the catalog is brand IP: every block name, every setting