@shoppexio/builder-contracts 0.1.0 → 0.1.2

package/src/custom-pages.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS,
+  mergeCustomPagesIntoManifest,
+} from './custom-pages.ts';
+import { CustomPageSchema } from './builder-settings.ts';
+import { createEmptyBuilderSettings } from './migrations.ts';
+import { convertLegacyThemeManifest } from './legacy-manifest.ts';
+import { validateBuilderSettingsAgainstManifest } from './validation.ts';
+
+function loadDefaultManifest() {
+  const manifestPath = join(import.meta.dir, '../../../themes/default/theme.manifest.json');
+  return convertLegacyThemeManifest(JSON.parse(readFileSync(manifestPath, 'utf8')) as unknown);
+}
+
+describe('custom pages manifest merge', () => {
+  test('keeps MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS aligned with config SSOT', () => {
+    const configPath = join(import.meta.dir, '../../../config/builder-shared-manifest-blocks.json');
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      customPageAllowedBlocks: string[];
+    };
+
+    expect([...MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS]).toEqual(config.customPageAllowedBlocks);
+  });
+
+  test('merges merchant custom pages into the effective manifest', () => {
+    const manifest = loadDefaultManifest();
+    const settings = createEmptyBuilderSettings(1);
+    settings.theme.pages = [
+      {
+        id: 'custom-about',
+        title: 'About Us',
+        slug: 'about-us',
+        visible: true,
+        layout: { blocks: [] },
+      },
+    ];
+    settings.theme.layout['custom-about'] = {
+      blocks: [
+        {
+          id: 'youtube-1',
+          type: 'youtube-embed',
+          visible: true,
+          settings: {
+            videoUrl: 'https://youtu.be/dQw4w9WgXcQ',
+          },
+        },
+      ],
+    };
+
+    const effective = mergeCustomPagesIntoManifest(manifest, settings);
+    expect(effective.pages['custom-about']).toEqual({
+      label: 'About Us',
+      previewPath: '/page/about-us',
+      allowedBlocks: expect.arrayContaining(['youtube-embed', 'custom-html']),
+      defaultBlocks: [],
+    });
+    expect(validateBuilderSettingsAgainstManifest(settings, manifest)).toEqual([]);
+  });
+
+  test('rejects multi-segment custom page slugs', () => {
+    const result = CustomPageSchema.safeParse({
+      id: 'custom-help-faq',
+      title: 'Help FAQ',
+      slug: 'help/faq',
+      visible: true,
+      layout: { blocks: [] },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/custom-pages.ts

@@ -0,0 +1,70 @@
+import type { BuilderSettings } from './builder-settings.ts';
+import type { ManifestPage, ThemeManifest } from './theme-manifest.ts';
+
+/**
+ * Allowed embed/content blocks on merchant custom pages (`theme.pages[]`).
+ * Keep aligned with `customPageAllowedBlocks` in
+ * `config/builder-shared-manifest-blocks.json`.
+ */
+export const MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS = [
+  'custom-html',
+  'youtube-embed',
+  'text-block',
+] as const;
+
+export type MerchantCustomPageAllowedBlock =
+  (typeof MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS)[number];
+
+export function resolveMerchantCustomPageAllowedBlocks(
+  manifest: ThemeManifest,
+): string[] {
+  return MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS.filter(
+    (blockType) => blockType in manifest.blocks,
+  );
+}
+
+export function buildMerchantCustomPageManifestEntry(
+  customPage: BuilderSettings['theme']['pages'][number],
+  manifest: ThemeManifest,
+): ManifestPage {
+  return {
+    label: customPage.title,
+    previewPath: `/page/${customPage.slug}`,
+    allowedBlocks: resolveMerchantCustomPageAllowedBlocks(manifest),
+    defaultBlocks: [],
+  };
+}
+
+export function mergeCustomPagesIntoManifest(
+  manifest: ThemeManifest,
+  settings: BuilderSettings,
+): ThemeManifest {
+  if (settings.theme.pages.length === 0) {
+    return manifest;
+  }
+
+  const pages = { ...manifest.pages };
+  for (const customPage of settings.theme.pages) {
+    if (pages[customPage.id]) {
+      continue;
+    }
+
+    pages[customPage.id] = buildMerchantCustomPageManifestEntry(customPage, manifest);
+  }
+
+  return { ...manifest, pages };
+}
+
+export function findCustomPageBySlug(
+  settings: BuilderSettings,
+  slug: string,
+): BuilderSettings['theme']['pages'][number] | undefined {
+  return settings.theme.pages.find((page) => page.slug === slug);
+}
+
+export function findCustomPageById(
+  settings: BuilderSettings,
+  pageId: string,
+): BuilderSettings['theme']['pages'][number] | undefined {
+  return settings.theme.pages.find((page) => page.id === pageId);
+}

package/src/dedicated-pages.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createDedicatedPageBlockType,
+  dedicatedPageContentKey,
+  dedicatedPagePreviewPath,
+  migrateDedicatedPageContent,
+  migrateDedicatedPageLayout,
+  normalizeDedicatedPageId,
+} from './dedicated-pages.ts';
+
+describe('dedicated-pages', () => {
+  test('normalizeDedicatedPageId maps legacy reviews id', () => {
+    expect(normalizeDedicatedPageId('reviews')).toBe('reviews-page');
+    expect(normalizeDedicatedPageId('faq-page')).toBe('faq-page');
+  });
+
+  test('createDedicatedPageBlockType follows page-{pageId} rule', () => {
+    expect(createDedicatedPageBlockType('faq-page')).toBe('page-faq-page');
+    expect(createDedicatedPageBlockType('reviews-page')).toBe('page-reviews-page');
+    expect(createDedicatedPageBlockType('reviews')).toBe('page-reviews');
+  });
+
+  test('dedicatedPagePreviewPath resolves known storefront paths', () => {
+    expect(dedicatedPagePreviewPath('contact-page')).toBe('/contact');
+    expect(dedicatedPagePreviewPath('reviews')).toBe('/reviews');
+    expect(dedicatedPagePreviewPath('home')).toBeNull();
+  });
+
+  test('dedicatedPageContentKey uses canonical page id', () => {
+    expect(dedicatedPageContentKey('reviews', 'title')).toBe('pages.reviews-page.title');
+  });
+
+  test('migrateDedicatedPageLayout renames legacy reviews page layout', () => {
+    const migrated = migrateDedicatedPageLayout({
+      home: { blocks: [] },
+      reviews: {
+        blocks: [{ id: 'reviews-1', type: 'page-reviews', visible: true, settings: {} }],
+      },
+    });
+
+    expect(migrated.reviews).toBeUndefined();
+    expect(migrated['reviews-page']).toMatchObject({
+      blocks: [{ id: 'reviews-1', type: 'page-reviews-page', visible: true, settings: {} }],
+    });
+  });
+
+  test('migrateDedicatedPageContent renames legacy content keys', () => {
+    const migrated = migrateDedicatedPageContent({
+      'pages.reviews.title': 'Reviews',
+      'tool.title': 'Free Tool',
+      'hero.title': 'Home',
+    });
+
+    expect(migrated['pages.reviews.title']).toBeUndefined();
+    expect(migrated['pages.reviews-page.title']).toBe('Reviews');
+    expect(migrated['tool.title']).toBeUndefined();
+    expect(migrated['pages.tool-page.title']).toBe('Free Tool');
+    expect(migrated['hero.title']).toBe('Home');
+  });
+
+  test('migrateDedicatedPageLayout renames legacy vault tool page', () => {
+    const migrated = migrateDedicatedPageLayout({
+      tool: {
+        blocks: [{
+          id: 'tool-1',
+          type: 'tool',
+          visible: true,
+          settings: { 'tool.title': 'Free Tool' },
+        }],
+      },
+    });
+
+    expect(migrated.tool).toBeUndefined();
+    expect(migrated['tool-page']).toMatchObject({
+      blocks: [{
+        id: 'tool-1',
+        type: 'page-tool-page',
+        visible: true,
+        settings: { 'pages.tool-page.title': 'Free Tool' },
+      }],
+    });
+  });
+
+  test('dedicatedPagePreviewPath resolves tool-page', () => {
+    expect(dedicatedPagePreviewPath('tool-page')).toBe('/tool');
+    expect(dedicatedPagePreviewPath('tool')).toBe('/tool');
+  });
+});

package/src/dedicated-pages.ts

@@ -0,0 +1,173 @@
+export const BUILDER_LAYOUT_PAGE_IDS = [
+  'home',
+  'navigation',
+  'product',
+  'footer',
+  'terms',
+] as const;
+
+export type BuilderLayoutPageId = (typeof BUILDER_LAYOUT_PAGE_IDS)[number];
+
+export const BUILDER_DEDICATED_PAGE_IDS = [
+  'contact-page',
+  'faq-page',
+  'reviews-page',
+  'feedback-page',
+  'guide-page',
+  'status-page',
+  'checkout-page',
+  'tool-page',
+] as const;
+
+export type BuilderDedicatedPageId = (typeof BUILDER_DEDICATED_PAGE_IDS)[number];
+
+/** @deprecated Legacy manifest page ids migrated on settings load. */
+export const DEDICATED_PAGE_ID_ALIASES: Readonly<Record<string, BuilderDedicatedPageId>> = {
+  reviews: 'reviews-page',
+  tool: 'tool-page',
+};
+
+const DEDICATED_PAGE_PREVIEW_PATHS: Readonly<Record<BuilderDedicatedPageId, string>> = {
+  'contact-page': '/contact',
+  'faq-page': '/faq',
+  'reviews-page': '/reviews',
+  'feedback-page': '/feedback',
+  'guide-page': '/guide',
+  'status-page': '/status',
+  'checkout-page': '/checkout',
+  'tool-page': '/tool',
+};
+
+export function normalizeDedicatedPageId(pageId: string): string {
+  return DEDICATED_PAGE_ID_ALIASES[pageId] ?? pageId;
+}
+
+export function isDedicatedPageId(pageId: string): pageId is BuilderDedicatedPageId {
+  return (BUILDER_DEDICATED_PAGE_IDS as readonly string[]).includes(pageId);
+}
+
+export function dedicatedPagePreviewPath(pageId: string): string | null {
+  const normalized = normalizeDedicatedPageId(pageId);
+  if (!isDedicatedPageId(normalized)) {
+    return null;
+  }
+  return DEDICATED_PAGE_PREVIEW_PATHS[normalized];
+}
+
+export function dedicatedPageContentKey(pageId: string, field: string): string {
+  return `pages.${normalizeDedicatedPageId(pageId)}.${field}`;
+}
+
+export function normalizeDedicatedPageBlockType(pageId: string): string {
+  return createDedicatedPageBlockType(normalizeDedicatedPageId(pageId));
+}
+
+export function createDedicatedPageBlockType(pageId: string): string {
+  const normalizedPageId = pageId
+    .toLowerCase()
+    .replace(/[^a-z0-9\-_.]+/g, '-')
+    .replace(/^[-_.]+/, '');
+  return `page-${normalizedPageId || 'custom'}`;
+}
+
+function migrateDedicatedPageBlockSettings(settings: unknown): Record<string, unknown> {
+  if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+    return {};
+  }
+
+  const next: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(settings)) {
+    if (key.startsWith('tool.')) {
+      next[`pages.tool-page.${key.slice('tool.'.length)}`] = value;
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+}
+
+export function migrateDedicatedPageLayout(layout: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...layout };
+
+  for (const [legacyId, canonicalId] of Object.entries(DEDICATED_PAGE_ID_ALIASES)) {
+    if (!Object.prototype.hasOwnProperty.call(next, legacyId)) {
+      continue;
+    }
+
+    const legacyLayout = next[legacyId];
+    delete next[legacyId];
+
+    if (Object.prototype.hasOwnProperty.call(next, canonicalId)) {
+      continue;
+    }
+
+    if (typeof legacyLayout !== 'object' || legacyLayout === null || Array.isArray(legacyLayout)) {
+      continue;
+    }
+
+    const blocks = (legacyLayout as { blocks?: unknown }).blocks;
+    if (!Array.isArray(blocks)) {
+      next[canonicalId] = legacyLayout;
+      continue;
+    }
+
+    const legacyBlockType = createDedicatedPageBlockType(legacyId);
+    const canonicalBlockType = createDedicatedPageBlockType(canonicalId);
+
+    next[canonicalId] = {
+      ...legacyLayout,
+      blocks: blocks.map((block) => {
+        if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+          return block;
+        }
+        const typed = block as { type?: unknown };
+        const isLegacyBlockType = typed.type === legacyBlockType
+          || (legacyId === 'tool' && typed.type === 'tool');
+        if (!isLegacyBlockType) {
+          return block;
+        }
+        return {
+          ...typed,
+          type: canonicalBlockType,
+          settings: migrateDedicatedPageBlockSettings(
+            (typed as { settings?: unknown }).settings,
+          ),
+        };
+      }),
+    };
+  }
+
+  return next;
+}
+
+export function migrateDedicatedPageContent(content: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...content };
+
+  for (const [key, value] of Object.entries(next)) {
+    if (key.startsWith('tool.') && !key.startsWith('tool-page.')) {
+      const canonicalKey = `pages.tool-page.${key.slice('tool.'.length)}`;
+      if (!Object.prototype.hasOwnProperty.call(next, canonicalKey)) {
+        next[canonicalKey] = value;
+      }
+      delete next[key];
+    }
+  }
+
+  for (const [legacyId, canonicalId] of Object.entries(DEDICATED_PAGE_ID_ALIASES)) {
+    const legacyPrefix = `pages.${legacyId}.`;
+    const canonicalPrefix = `pages.${canonicalId}.`;
+
+    for (const [key, value] of Object.entries(next)) {
+      if (!key.startsWith(legacyPrefix)) {
+        continue;
+      }
+      const canonicalKey = `${canonicalPrefix}${key.slice(legacyPrefix.length)}`;
+      if (!Object.prototype.hasOwnProperty.call(next, canonicalKey)) {
+        next[canonicalKey] = value;
+      }
+      delete next[key];
+    }
+  }
+
+  return next;
+}

package/src/events.ts

@@ -102,6 +102,13 @@ const TermsSetEventSchema = EventBaseSchema.extend({
   value: z.string(),
 }).strict();
 
+const PresetApplyEventSchema = EventBaseSchema.extend({
+  type: z.literal('preset.apply'),
+  pageId: PageIdSchema,
+  presetId: z.string().min(1),
+  blockId: z.string().min(1).optional(),
+}).strict();
+
 export const BuilderEventSchema = z.discriminatedUnion('type', [
   ContentSetEventSchema,
   ListSetEventSchema,
@@ -117,5 +124,6 @@ export const BuilderEventSchema = z.discriminatedUnion('type', [
   PageUpsertEventSchema,
   PageRemoveEventSchema,
   TermsSetEventSchema,
+  PresetApplyEventSchema,
 ]);
 export type BuilderEvent = z.infer<typeof BuilderEventSchema>;

package/src/fields.ts

@@ -7,6 +7,11 @@ const FieldBaseSchema = z
     description: z.string().min(1).optional(),
     defaultValue: z.unknown().optional(),
     required: z.boolean().optional(),
+    // Groups settings within the Inspector. "content" (default) shows
+    // under the Block Settings collapsible; "profile" shows under Profile
+    // banner; "style" shows under Style; "search" shows under Search bar.
+    // Themes pick up the value via the existing block.settings.path lookup.
+    group: z.enum(['content', 'profile', 'style', 'search']).optional(),
   })
   .strict();
 
@@ -30,6 +35,30 @@ const RichTextFieldSchema = FieldBaseSchema.extend({
   allowedMarks: z.array(z.enum(['bold', 'italic', 'link', 'code'])).optional(),
 }).strict();
 
+// Plain-text source code field. Renders a Monaco editor in the
+// Inspector and persists the raw string back into block.settings.
+// Used by the `custom-html` block (and any future block that needs
+// a code-shaped setting). Themes interpret the string however they
+// see fit — sandboxed iframe srcDoc for HTML, etc.
+const CodeFieldTemplateSchema = z
+  .object({
+    label: z.string().min(1),
+    snippet: z.string().min(1),
+    description: z.string().min(1).optional(),
+  })
+  .strict();
+export type CodeFieldTemplate = z.infer<typeof CodeFieldTemplateSchema>;
+
+const CodeFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('code'),
+  language: z.enum(['html', 'css', 'javascript', 'json']).optional(),
+  placeholder: z.string().optional(),
+  maxLength: z.number().int().positive().optional(),
+  // Optional quick-insert chips rendered above the editor. Clicking a
+  // template replaces the field value with the snippet.
+  templates: z.array(CodeFieldTemplateSchema).optional(),
+}).strict();
+
 const ImageFieldSchema = FieldBaseSchema.extend({
   type: z.literal('image'),
   aspectRatio: z.string().min(1).optional(),
@@ -117,6 +146,7 @@ const ListFieldSchema = FieldBaseSchema.extend({
 export const BuilderFieldSchema = z.discriminatedUnion('type', [
   TextFieldSchema,
   RichTextFieldSchema,
+  CodeFieldSchema,
   ImageFieldSchema,
   LinkFieldSchema,
   BooleanFieldSchema,

package/src/index.ts

@@ -1,9 +1,19 @@
+export * from './custom-pages.ts';
+export * from './dedicated-pages.ts';
 export * from './builder-settings.ts';
+export * from './canonical-settings.ts';
 export * from './events.ts';
 export * from './fields.ts';
 export * from './legacy-manifest.ts';
 export * from './migrations.ts';
+export * from './persistence.ts';
+export * from './preview-boot.ts';
 export * from './preview-protocol.ts';
+export * from './preview-session-resolve.ts';
+export * from './preview-trusted-origins.ts';
+export * from './storefront-initial-data-html.ts';
+export * from './storefront-typography-fonts.ts';
 export * from './style-slots.ts';
 export * from './theme-manifest.ts';
+export * from './theme-schemes.ts';
 export * from './validation.ts';